@homepages/template-kit 0.0.1 → 0.2.0

package/dist/primitives/Slot.js

@@ -0,0 +1,39 @@
+import { ATTR_SLOT_ID, ATTR_SLOT_TEXT_LEAF } from "../contracts/markers.js";
+import { Children, cloneElement, isValidElement } from "react";
+import { jsx } from "react/jsx-runtime";
+
+//#region src/primitives/Slot.tsx
+/**
+* Slot — the canonical wrapper for an editable slot's DOM boundary.
+*
+* Wrap each editable slot's outer DOM in `<Slot id="…">`. It emits `data-slot-id`,
+* which is how the editor resolves a click in the preview back to the slot the user
+* meant. A slot with no marker in the DOM cannot be selected or edited.
+*
+* A primitive with a natural single root for its slot type takes a `slotId` prop and
+* emits the marker on its own root instead — `<Image slotId="hero_image">` needs no
+* `<Slot>` wrapper. `<Slot>` is for everything else: text slots, source-bound scalars
+* rendered as raw spans, and any slot whose markup is a hand-assembled composition.
+*/
+function Slot({ id, as, textLeaf, children, ...rest }) {
+	const Tag = as ?? "div";
+	const content = textLeaf ? markSingleTextLeaf(children) : children;
+	return /* @__PURE__ */ jsx(Tag, {
+		[ATTR_SLOT_ID]: id,
+		...rest,
+		children: content
+	});
+}
+function markSingleTextLeaf(children) {
+	if (Children.count(children) !== 1) return children;
+	const only = Children.toArray(children)[0];
+	if (!isValidElement(only)) return children;
+	const element = only;
+	return cloneElement(element, {
+		...element.props,
+		[ATTR_SLOT_TEXT_LEAF]: ""
+	});
+}
+
+//#endregion
+export { Slot };

package/dist/primitives/SlotGroup.d.ts

@@ -0,0 +1,38 @@
+import { ElementType, HTMLAttributes, ReactNode } from "react";
+//#region src/primitives/SlotGroup.d.ts
+type SlotGroupProps = HTMLAttributes<HTMLElement> & {
+  /**
+   * Must equal the `id` of a `meta.groups[]` entry in the section schema.
+   *
+   * Emitted as `data-slot-group` on the rendered container, so the editor treats
+   * the group as one selectable unit: selection chrome outlines THIS container
+   * rather than the individual members, and a click anywhere inside it —
+   * including the gaps between members — resolves to the group.
+   */
+  id: string;
+  /**
+   * Element to render. Defaults to `"div"`. Override when the group's surrounding
+   * semantic role needs something else.
+   */
+  as?: ElementType;
+  /**
+   * The member slots. `SlotGroup` MUST be an ANCESTOR of every member's
+   * `data-slot-id` element (it wraps their shared container) — the editor resolves
+   * a member back to its group with `closest("[data-slot-group]")`, so a marker
+   * that isn't an ancestor would never be found.
+   */
+  children?: ReactNode;
+};
+/**
+ * SlotGroup — the wrapper for a set of slots the schema groups into one editor card.
+ *
+ * Grouping is authored in two places that must agree. `meta.groups[]` declares the
+ * group (`{ id, label, members }`), which collapses its members into a single card in
+ * the editor sidebar. The renderer wraps those members' shared container in
+ * `<SlotGroup id="<the group's id>">`, which makes the canvas outline and select them
+ * as the one unit that matches that one card. Same id on both sides, or the card and
+ * the canvas disagree about what the user just clicked.
+ */
+declare function SlotGroup({ id, as, children, ...rest }: SlotGroupProps): ReactNode;
+//#endregion
+export { SlotGroup };

package/dist/primitives/SlotGroup.js

@@ -0,0 +1,24 @@
+import { ATTR_SLOT_GROUP } from "../contracts/markers.js";
+import { jsx } from "react/jsx-runtime";
+
+//#region src/primitives/SlotGroup.tsx
+/**
+* SlotGroup — the wrapper for a set of slots the schema groups into one editor card.
+*
+* Grouping is authored in two places that must agree. `meta.groups[]` declares the
+* group (`{ id, label, members }`), which collapses its members into a single card in
+* the editor sidebar. The renderer wraps those members' shared container in
+* `<SlotGroup id="<the group's id>">`, which makes the canvas outline and select them
+* as the one unit that matches that one card. Same id on both sides, or the card and
+* the canvas disagree about what the user just clicked.
+*/
+function SlotGroup({ id, as, children, ...rest }) {
+	return /* @__PURE__ */ jsx(as ?? "div", {
+		[ATTR_SLOT_GROUP]: id,
+		...rest,
+		children
+	});
+}
+
+//#endregion
+export { SlotGroup };

package/dist/primitives/SlotItem.d.ts

@@ -0,0 +1,43 @@
+import { ElementType, HTMLAttributes, ReactNode } from "react";
+//#region src/primitives/SlotItem.d.ts
+type SlotItemProps = HTMLAttributes<HTMLElement> & {
+  /**
+   * Zero-based position of this item within its collection slot — the item's
+   * index in the array the renderer is mapping over. Emitted as
+   * `data-slot-item`.
+   */
+  index: number;
+  /**
+   * Element to render. Defaults to `"div"`. Override when the item's surrounding
+   * semantic role needs something else (`li`, `article`, …).
+   */
+  as?: ElementType;
+  children?: ReactNode;
+};
+/**
+ * SlotItem — the per-item handle inside a collection slot (`object_list`,
+ * `image_collection`).
+ *
+ * A collection slot's `<Slot id="…">` marks the whole array; `<SlotItem index={i}>`
+ * marks one row of it. The editor needs BOTH: it resolves the slot from the ancestor
+ * `data-slot-id` and then the specific item from the nearest `data-slot-item`, which
+ * is what makes per-item selection, per-item image cropping, and per-item live
+ * surfaces work. Without it a collection is editable only as a whole.
+ *
+ * The index must be the item's position in the slot's array as rendered. The editor
+ * writes edits back by that index, so a `SlotItem` whose index doesn't match its
+ * position edits the wrong row.
+ *
+ * ```tsx
+ * <Slot id="amenities">
+ *   {items.map((item, i) => (
+ *     <SlotItem key={item.id} index={i} className="border-b">
+ *       …
+ *     </SlotItem>
+ *   ))}
+ * </Slot>
+ * ```
+ */
+declare function SlotItem({ index, as, children, ...rest }: SlotItemProps): ReactNode;
+//#endregion
+export { SlotItem };

package/dist/primitives/SlotItem.js

@@ -0,0 +1,38 @@
+import { ATTR_SLOT_ITEM } from "../contracts/markers.js";
+import { jsx } from "react/jsx-runtime";
+
+//#region src/primitives/SlotItem.tsx
+/**
+* SlotItem — the per-item handle inside a collection slot (`object_list`,
+* `image_collection`).
+*
+* A collection slot's `<Slot id="…">` marks the whole array; `<SlotItem index={i}>`
+* marks one row of it. The editor needs BOTH: it resolves the slot from the ancestor
+* `data-slot-id` and then the specific item from the nearest `data-slot-item`, which
+* is what makes per-item selection, per-item image cropping, and per-item live
+* surfaces work. Without it a collection is editable only as a whole.
+*
+* The index must be the item's position in the slot's array as rendered. The editor
+* writes edits back by that index, so a `SlotItem` whose index doesn't match its
+* position edits the wrong row.
+*
+* ```tsx
+* <Slot id="amenities">
+*   {items.map((item, i) => (
+*     <SlotItem key={item.id} index={i} className="border-b">
+*       …
+*     </SlotItem>
+*   ))}
+* </Slot>
+* ```
+*/
+function SlotItem({ index, as, children, ...rest }) {
+	return /* @__PURE__ */ jsx(as ?? "div", {
+		[ATTR_SLOT_ITEM]: index,
+		...rest,
+		children
+	});
+}
+
+//#endregion
+export { SlotItem };

package/dist/primitives/index.d.ts

@@ -0,0 +1,7 @@
+import { Image } from "./Image.js";
+import { PicturePlan, PictureSourceSpec } from "./picture-sources.js";
+import { Section } from "./Section.js";
+import { Slot } from "./Slot.js";
+import { SlotGroup } from "./SlotGroup.js";
+import { SlotItem } from "./SlotItem.js";
+export { Image, type PicturePlan, type PictureSourceSpec, Section, Slot, SlotGroup, SlotItem };

package/dist/primitives/picture-sources.d.ts

@@ -0,0 +1,22 @@
+//#region src/primitives/picture-sources.d.ts
+type PictureSourceSpec = {
+  type?: string;
+  media?: string;
+  srcSet: string;
+  sizes?: string;
+};
+type PicturePlan = {
+  /**
+   * Ordered <source> specs: mobile (media-gated) first, then desktop. May be empty
+   * even with a valid plan (a single-format descriptor puts everything on the <img>);
+   * `sources: []` AND no `imgSrcSet` is the "no responsive — caller degrades" signal.
+   */
+  sources: PictureSourceSpec[];
+  /** srcset for the trailing <img> (the desktop base raster). */
+  imgSrcSet?: string;
+  imgSizes?: string;
+  width?: number;
+  height?: number;
+};
+//#endregion
+export { PicturePlan, PictureSourceSpec };

package/dist/primitives/picture-sources.js

@@ -0,0 +1,52 @@
+//#region src/primitives/picture-sources.ts
+function capSrcset(srcset, maxRungWidth) {
+	const entries = srcset.split(",").map((s) => s.trim()).filter(Boolean).map((cand) => {
+		const m = cand.match(/(\d+)w\s*$/);
+		return {
+			cand,
+			w: m ? Number(m[1]) : Number.POSITIVE_INFINITY
+		};
+	}).sort((a, b) => a.w - b.w);
+	if (entries.length === 0) return srcset;
+	if (maxRungWidth == null) return entries.map((event) => event.cand).join(", ");
+	const kept = entries.filter((event) => event.w <= maxRungWidth);
+	return (kept.length > 0 ? kept : [entries[0]]).map((event) => event.cand).join(", ");
+}
+function buildPictureSources(args) {
+	const { responsive, responsiveMobile, sizes, maxRungWidth, mobileBreakpoint } = args;
+	if (!responsive || responsive.sources.length === 0) return { sources: [] };
+	const sources = [];
+	if (responsiveMobile && responsiveMobile.sources.length > 0 && mobileBreakpoint) {
+		const media = `(max-width: ${mobileBreakpoint - 1}px)`;
+		const m = responsiveMobile.sources;
+		const mBase = m[m.length - 1];
+		for (const s of m.slice(0, -1)) sources.push({
+			type: s.type,
+			media,
+			srcSet: capSrcset(s.srcset, maxRungWidth),
+			sizes
+		});
+		sources.push({
+			media,
+			srcSet: capSrcset(mBase.srcset, maxRungWidth),
+			sizes
+		});
+	}
+	const d = responsive.sources;
+	const dBase = d[d.length - 1];
+	for (const s of d.slice(0, -1)) sources.push({
+		type: s.type,
+		srcSet: capSrcset(s.srcset, maxRungWidth),
+		sizes
+	});
+	return {
+		sources,
+		imgSrcSet: capSrcset(dBase.srcset, maxRungWidth),
+		imgSizes: sizes,
+		width: responsive.width,
+		height: responsive.height
+	};
+}
+
+//#endregion
+export { buildPictureSources };

package/dist/rules/registry.js

@@ -0,0 +1,16 @@
+//#region src/rules/registry.ts
+/**
+* `no-hex` → `docs/rules/no-hex.md`.
+*
+* Package-relative on purpose: the caller decides what to resolve it against. A
+* printer prefixes the resolved package root so an author sees a path they can open
+* with no network (`node_modules/@homepages/template-kit/docs/rules/no-hex.md`);
+* ESLint's `meta.docs.url` uses it as-is. This module never touches the filesystem —
+* the ESLint preset imports it.
+*/
+function docsPathForRule(id) {
+	return `docs/rules/${id}.md`;
+}
+
+//#endregion
+export { docsPathForRule };