@homepages/template-kit 0.0.1 → 0.2.0

package/docs/rules/size-renderer-bundle.md

@@ -0,0 +1,109 @@
+---
+purpose: The template-kit/size-renderer-bundle authoring rule — what it enforces, why, and how to fix it.
+status: living
+related: [INDEX.md, size-section-css.md]
+updated: 2026-07-14
+---
+# template-kit/size-renderer-bundle
+
+> A section's renderer bundle must be **≤ 50 KB gzip**. The budget is not
+> author-overridable.
+
+## Rule
+
+Each section's renderer is bundled with esbuild and minified, with **React treated as
+external** (it is a peer, shared by the whole page, and is not counted against any one
+section). The gzipped result must be **50 KB or less**.
+
+The budget is **visible in `template-kit check`'s configuration and is not
+author-overridable**. A template workspace cannot raise it, and there is no per-section
+exemption. If you go looking for the flag, this is the answer: there isn't one.
+
+## Reason
+
+The output is a real page for a real buyer, standing in a driveway on a phone. Bytes are the
+one cost the section cannot delegate.
+
+The number is set to be generous — roughly **twice** the largest section shipping today — so
+it does not fight ordinary authoring. You will not hit it by writing a rich section. You hit
+it when something **runaway** gets pulled in:
+
+- **a barrel import of an icon set**, which drags every icon into the bundle so you can use
+  three;
+- **a package that brings a font, a locale table, or a polyfill along with it**, none of
+  which you asked for.
+
+That is the shape of essentially every violation: not a section that grew, but a single
+import that was more expensive than it looked.
+
+## Fix
+
+Find the import that is not paying for itself.
+
+- **Import named symbols, never a namespace.** `import { ArrowRight } from "…"` is
+  tree-shakeable; `import * as Icons from "…"` is not — a namespace object has to contain
+  everything, so nothing can be dropped.
+- **Prefer the package's narrow entry** if it offers one.
+- **Hand-write the residue.** If you use one function out of a large utility package, copy
+  the function.
+
+**Do not try to hoist code out of the section to dodge the budget.** Each template owns its
+own presentation code; there is no shared library above a section to hoist it into, and the
+bytes would still land on the same page.
+
+### Before
+
+```tsx
+// sections/amenities/Renderer.tsx
+import { Section, Slot, SlotItem } from "@homepages/template-kit";
+import * as Icons from "lucide-react"; // ← the whole set: every icon, in the bundle
+
+import type { Props } from "./schema.js";
+
+export function Renderer({ slots }: Props) {
+  return (
+    <Section>
+      <Slot id="amenities">
+        {slots.amenities.map((item, i) => (
+          <SlotItem key={typeof item.id === "string" ? item.id : i} index={i} as="li">
+            <Icons.Check aria-hidden />
+            <h3>{typeof item.label === "string" ? item.label : null}</h3>
+          </SlotItem>
+        ))}
+      </Slot>
+    </Section>
+  );
+}
+```
+
+### After
+
+```tsx
+// sections/amenities/Renderer.tsx
+import { Section, Slot, SlotItem } from "@homepages/template-kit";
+import { Check } from "lucide-react"; // ← one icon, and the bundler can drop the rest
+
+import type { Props } from "./schema.js";
+
+export function Renderer({ slots }: Props) {
+  return (
+    <Section>
+      <Slot id="amenities">
+        {slots.amenities.map((item, i) => (
+          <SlotItem key={typeof item.id === "string" ? item.id : i} index={i} as="li">
+            <Check aria-hidden />
+            <h3>{typeof item.label === "string" ? item.label : null}</h3>
+          </SlotItem>
+        ))}
+      </Slot>
+    </Section>
+  );
+}
+```
+
+## See also
+
+- [`size-section-css`](size-section-css.md) — the same budget on the other half of what the
+  section ships.
+- [`license-denied`](license-denied.md) — the other reason to look hard at a dependency
+  before you take it.

package/docs/rules/size-section-css.md

@@ -0,0 +1,95 @@
+---
+purpose: The template-kit/size-section-css authoring rule — what it enforces, why, and how to fix it.
+status: living
+related: [INDEX.md, size-renderer-bundle.md, ../theme-and-css.md]
+updated: 2026-07-14
+---
+# template-kit/size-section-css
+
+> A section's compiled CSS must be **≤ 50 KB gzip** — **including the package CSS its module
+> graph imports.** That inclusion is the whole point of the rule.
+
+## Rule
+
+A section's compiled cascade layer must gzip to **50 KB or less**. What is measured is
+everything that lands in the layer:
+
+- the section's hand-written CSS, and
+- **every package stylesheet its module graph imports** — the `import "swiper/css"` in a
+  component, an island, or a marked enhancer.
+
+The budget is **visible in `template-kit check`'s configuration and is not
+author-overridable**. A workspace cannot raise it, and there is no per-section exemption.
+
+## Reason
+
+Same page, same phone, same buyer as
+[`size-renderer-bundle`](size-renderer-bundle.md) — and here the bytes are worse, because
+CSS blocks the first paint.
+
+"Including package CSS" is not a technicality; it is the failure this rule exists to catch.
+Your own stylesheet is almost never the problem — it is a few kilobytes of overrides. The
+package's is. And the reason it is invisible to you is the mechanism: a package stylesheet's
+`url()` references — its icon sprites, its webfont — are **inlined as `data:` URIs** into the
+compiled stylesheet. A 300 KB font file arrives in your published CSS without you ever
+having seen a 300 KB file. Nothing in your source looks large. Nothing in the package's
+`dist` listing looks alarming. The compiled layer is 400 KB.
+
+So the number this check reports is frequently the first time anyone finds out what a
+one-line CSS import actually cost.
+
+## Fix
+
+Three moves, in order of how often they work:
+
+1. **Import the slimmest entry the package offers.** Most CSS-shipping packages have a core
+   stylesheet plus opt-in modules, *and* a fat "everything" bundle that is the one you get
+   from copying the quickstart. Take the core, plus only the modules you use.
+2. **Cut the webfont.** If the package's stylesheet drags in a font for its icons, and you
+   are using three of those icons, replace them with inline SVG — or with a family the page's
+   theme already declares (`--tr-font-sans`, `--tr-font-serif`), which costs nothing
+   because it is already loaded.
+3. **Drop the package and hand-write the residue.** If you use one component from a large
+   widget library, its stylesheet is paying for components you never render.
+
+### Before
+
+```tsx
+// sections/gallery/Carousel.tsx
+"use client";
+
+import Swiper from "swiper";
+import "swiper/swiper-bundle.css"; // ← every module Swiper ships, plus its icon font
+
+export default function Carousel({ slides }: { slides: { id: string; url: string }[] }) {
+  // …uses navigation arrows and pagination dots, and nothing else
+}
+```
+
+### After
+
+```tsx
+// sections/gallery/Carousel.tsx
+"use client";
+
+import Swiper from "swiper";
+import "swiper/css";            // ← the core layout only
+import "swiper/css/navigation"; // ← the two modules this carousel actually uses
+import "swiper/css/pagination";
+
+export default function Carousel({ slides }: { slides: { id: string; url: string }[] }) {
+  // …
+}
+```
+
+The arrows and dots that came from the bundle's icon font are drawn as inline SVG in the
+component instead, so nothing pulls a webfont into the layer.
+
+## See also
+
+- [`size-renderer-bundle`](size-renderer-bundle.md) — the same budget on the section's
+  JavaScript.
+- [`no-bare-css-import`](no-bare-css-import.md) — why a package's stylesheet is imported from
+  code and never `@import`ed from CSS.
+- [Theme and CSS](../theme-and-css.md) — the fonts and tokens the page already loads, which
+  cost you nothing to reuse.

package/docs/rules/slot-group-marker.md

@@ -0,0 +1,127 @@
+---
+purpose: The template-kit/slot-group-marker authoring rule — what it enforces, why, and how to fix it.
+status: living
+related: [INDEX.md, ../primitives.md, ../schema-system.md]
+updated: 2026-07-14
+---
+# template-kit/slot-group-marker
+
+> A group declared in `meta.groups` with **two or more members** must be wrapped in
+> `<SlotGroup id="…">` in the JSX. Grouping is authored in two places, and they must agree.
+
+## Rule
+
+For every entry in `schema.ts`'s `meta.groups` whose flattened member list has **≥ 2
+members**, the section's JSX must contain `<SlotGroup id="<that group's id>">` wrapping a
+container that is a **shared ancestor** of every member's marker.
+
+"Flattened" is literal: `members: ["agent_name", ["agent_email", "agent_phone"]]` is three
+members, not two — a `[a, b]` tuple is a 2-up row, not a single member.
+
+Membership is read from the typed `meta.groups` block. The check never guesses a group by
+scanning your markup for things that look related.
+
+Carve-outs:
+
+- **A 1-member group needs no wrapper.** One slot, one card — the group adds no grouping
+  the marker isn't already doing.
+- **A single slot rendered more than once is not a group.** An address shown in both a
+  desktop and a mobile layout is one slot in two places; it needs no `meta.groups` entry
+  and no `<SlotGroup>`.
+
+## Reason
+
+`meta.groups` makes the editor collapse several slots into **one accordion card** in the
+sidebar. The `<SlotGroup>` wrapper is the other half of that promise: the canvas outlines
+and selects the group as **one unit**, because its hover/selection chrome targets the
+`data-slot-group` container.
+
+Declare the group and omit the wrapper and the two halves disagree. The sidebar shows one
+card, and the canvas — with no group container to find — falls back to outlining the
+members one at a time. The user sees a single "Agent" card that highlights three separate
+boxes on the page.
+
+`SlotGroup` must be an **ancestor** of every member's `data-slot-id` element, because the
+editor resolves the group with `closest("[data-slot-group]")` from the clicked slot. A
+marker that sits beside the members rather than around them is never found.
+
+## Fix
+
+Wrap the members' shared container in `<SlotGroup id="…">`, using the **same id** as the
+`meta.groups` entry. If the slots do not actually edit as a unit, the other honest fix is
+to delete the group from `meta.groups` — then each slot is its own card and no wrapper is
+wanted.
+
+### Before
+
+```ts
+// sections/contact/schema.ts
+import type { SectionProps, SectionSchemaShape } from "@homepages/template-kit";
+
+export const schema = {
+  meta: {
+    displayName: "Contact",
+    groups: [
+      { id: "agent", label: "Agent", members: ["agent_name", ["agent_email", "agent_phone"]] },
+    ],
+  },
+  slots: {
+    agent_name: { type: "text", size: "short", required: true, editable_by_user: true },
+    agent_email: { type: "text", size: "short", required: false, editable_by_user: true },
+    agent_phone: { type: "text", size: "short", required: false, editable_by_user: true },
+  },
+} as const satisfies SectionSchemaShape;
+
+export type Props = SectionProps<typeof schema>;
+```
+
+```tsx
+// sections/contact/Renderer.tsx — template-kit/slot-group-marker: agent
+import { Section, Slot } from "@homepages/template-kit";
+
+import type { Props } from "./schema.js";
+
+export function Renderer({ slots }: Props) {
+  return (
+    <Section>
+      <div className="flex flex-col gap-2">
+        <Slot id="agent_name" textLeaf><h3>{slots.agent_name}</h3></Slot>
+        <Slot id="agent_email" textLeaf><span>{slots.agent_email}</span></Slot>
+        <Slot id="agent_phone" textLeaf><span>{slots.agent_phone}</span></Slot>
+      </div>
+    </Section>
+  );
+}
+```
+
+### After
+
+The container was already there — it just needed to be the group:
+
+```tsx
+// sections/contact/Renderer.tsx
+import { Section, Slot, SlotGroup } from "@homepages/template-kit";
+
+import type { Props } from "./schema.js";
+
+export function Renderer({ slots }: Props) {
+  return (
+    <Section>
+      <SlotGroup id="agent" className="flex flex-col gap-2">
+        <Slot id="agent_name" textLeaf><h3>{slots.agent_name}</h3></Slot>
+        <Slot id="agent_email" textLeaf><span>{slots.agent_email}</span></Slot>
+        <Slot id="agent_phone" textLeaf><span>{slots.agent_phone}</span></Slot>
+      </SlotGroup>
+    </Section>
+  );
+}
+```
+
+## See also
+
+- [Contract primitives: `SlotGroup`](../primitives.md#slotgroup--slots-edited-as-one-unit) —
+  the ancestor requirement and what the marker does.
+- [The schema system](../schema-system.md#grouping-slots-into-one-editor-card) — grouping is
+  declared in `meta.groups`; there is no per-slot `group` field.
+- [`missing-slot-marker`](missing-slot-marker.md) — the per-slot marker each member still
+  needs.

package/docs/rules/slot-marker-literal.md

@@ -0,0 +1,148 @@
+---
+purpose: The template-kit/slot-marker-literal authoring rule — what it enforces, why, and how to fix it.
+status: living
+related: [INDEX.md, ../primitives.md, ../schema-system.md]
+updated: 2026-07-14
+---
+# template-kit/slot-marker-literal
+
+> A slot key must be written as a string literal wherever it is marked. `SlotItem` is
+> exempt.
+
+## Rule
+
+These four places carry a slot key, and each must be a **string literal**:
+
+| Where | Example |
+|---|---|
+| `<Slot id>` | `<Slot id="headline">` |
+| `<SlotGroup id>` | `<SlotGroup id="agent">` |
+| `slotId` on any element | `<Image slotId="hero_image" …>` |
+| `data-slot-id` / `data-slot-group` on any element | `<div data-slot-id="headline">` |
+
+Anything that is not a plain string literal reports: an expression (`<Slot id={key}>`), a
+template literal (`` <Slot id={`slot_${n}`}> ``), and a valueless attribute
+(`<div data-slot-id>`).
+
+**`SlotItem` is deliberately exempt.** Its prop is `index: number` — an array position,
+written `index={i}` inside a `.map()`, not a schema key. There is nothing to cross-check
+it against, so an expression there is correct and expected.
+
+## Reason
+
+This is not style. A separate, cross-file completeness check verifies that **every slot
+declared in `schema.ts` has a marker in the section's JSX** — and it reads these keys
+**statically**, from the source text, without running your Renderer.
+
+A key written as an expression is a key it cannot resolve. So the check cannot see the
+slot as marked, and — worse — the marker that actually reaches the browser is whatever
+your expression happened to evaluate to. The slot **silently loses editor selection**: it
+still fills, it still renders, and a user clicking on it in the editor selects nothing.
+Nothing throws. The failure is invisible until someone tries to edit that block.
+
+This rule exists **so that** [`missing-slot-marker`](missing-slot-marker.md) can work. A
+`.map()`-generated slot key defeats both at once: the completeness check reports the slot
+as unmarked, and no lint tells you why.
+
+## Fix
+
+This shows up in two different shapes, and the fix depends on which one you're in.
+
+**A key that is static but not literal** — held in a `const`, or assembled with a
+template literal — isn't generating anything: there is exactly one possible value, so
+unwrap it back into a plain inline string literal.
+
+**A key generated inside a `.map()` over an array** is a genuine collection: declare it
+as one slot in `schema.ts`, mark the array **once** with `<Slot>`, and mark each row with
+`<SlotItem index={i}>`.
+
+### Before
+
+```tsx
+import { Section, Slot } from "@homepages/template-kit";
+
+import type { Props } from "./schema.js";
+
+const FIELD = "headline";
+
+export function Renderer({ slots }: Props) {
+  return (
+    <Section>
+      <Slot id={FIELD} as="h1" textLeaf>
+        <span>{slots.headline}</span>
+      </Slot>
+      <Slot id={`sub${"title"}`} textLeaf>
+        <p>{slots.subtitle}</p>
+      </Slot>
+    </Section>
+  );
+}
+```
+
+Neither `FIELD` nor the template literal is doing any work — both spell out their whole
+value at the call site. That's the common case: a constant or a template literal standing
+in for a string that was always going to be one string.
+
+### After
+
+```tsx
+import { Section, Slot } from "@homepages/template-kit";
+
+import type { Props } from "./schema.js";
+
+export function Renderer({ slots }: Props) {
+  return (
+    <Section>
+      <Slot id="headline" as="h1" textLeaf>
+        <span>{slots.headline}</span>
+      </Slot>
+      <Slot id="subtitle" textLeaf>
+        <p>{slots.subtitle}</p>
+      </Slot>
+    </Section>
+  );
+}
+```
+
+The other shape is different: a key actually produced by iterating an array is modelling
+a real collection, and the fix is structural, not a matter of unwrapping.
+
+```tsx
+// Before — `.map()` produces a different key each iteration; none of them is a literal.
+const FIELDS = ["headline", "subhead"] as const;
+
+export function Renderer({ slots }: Props) {
+  return (
+    <Section>
+      {FIELDS.map((key) => (
+        <Slot key={key} id={key} textLeaf>
+          <p>{slots[key]}</p>
+        </Slot>
+      ))}
+    </Section>
+  );
+}
+```
+
+A genuine collection keeps its loop — the literal key is on the `<Slot>`, and the loop
+variable stays on `SlotItem`'s `index`, which is exempt:
+
+```tsx
+<Slot id="amenities">
+  {slots.amenities.map((item, i) => (
+    <SlotItem key={item.id} index={i} as="li">
+      <h3>{item.label}</h3>
+    </SlotItem>
+  ))}
+</Slot>
+```
+
+Don't reach for this structural rewrite for the first case above — a named constant or a
+template literal is not a collection, and modelling it as one is solving a problem you
+don't have.
+
+## See also
+
+- [Contract primitives](../primitives.md#the-marker-contract) — the marker attributes and
+  which primitive emits each.
+- [Schema system](../schema-system.md) — where slot keys are declared.

package/docs/rules/typecheck.md

@@ -0,0 +1,103 @@
+---
+purpose: The template-kit/typecheck authoring rule — what it enforces, why, and how to fix it.
+status: living
+related: [INDEX.md, ../schema-system.md]
+updated: 2026-07-14
+---
+# template-kit/typecheck
+
+> The template must compile. Every type error is one violation.
+
+## Rule
+
+The template's TypeScript must compile cleanly. The check resolves `typescript` from **your
+workspace's** `node_modules` — the compiler that runs is the one you installed, at the
+version you pinned, against your own `tsconfig.json`.
+
+If `typescript` is not installed, that is itself the diagnostic (with the fix), not a crash.
+
+## Reason
+
+The schema system is the section contract, and it is enforced **through the type system**.
+`SectionProps<typeof schema>` is not a convenience — it is the mechanism that keeps
+`schema.ts` and `Renderer.tsx` in agreement: a slot you add to the schema and forget to
+render, a slot you render under the wrong name, an optional slot you treat as always
+present, a slot whose type you assume wrong. Each of those is a compile error rather than a
+surprise on a stranger's published page.
+
+A template that does not typecheck has opted out of the only thing checking that the two
+files still describe the same section.
+
+## Fix
+
+Fix the type error. If the compiler itself is missing, install it and point your
+`tsconfig.json` at the kit's base config, which sets the module resolution and JSX settings
+the kit's types expect:
+
+```jsonc
+// tsconfig.json
+{ "extends": "@homepages/template-kit/tsconfig", "include": ["sections", "theme.ts"] }
+```
+
+```bash
+npm install --save-dev typescript
+```
+
+### Before
+
+`year_built` is declared `required: false`, so `SectionProps` resolves it to
+`string | null` — and the Renderer treats it as a `string`:
+
+```tsx
+// sections/facts/Renderer.tsx
+import { Section, Slot } from "@homepages/template-kit";
+
+import type { Props } from "./schema.js";
+
+export function Renderer({ slots }: Props) {
+  return (
+    <Section>
+      {/* error TS18047: 'slots.year_built' is possibly 'null'. */}
+      <Slot id="year_built" textLeaf>
+        <p>Built {slots.year_built.slice(0, 4)}</p>
+      </Slot>
+    </Section>
+  );
+}
+```
+
+That is not a pedantic complaint. `required: false` means a thin listing really does arrive
+with no year, and this line really does throw on it.
+
+### After
+
+```tsx
+// sections/facts/Renderer.tsx
+import { Section, Slot } from "@homepages/template-kit";
+
+import type { Props } from "./schema.js";
+
+export function Renderer({ slots }: Props) {
+  return (
+    <Section>
+      {slots.year_built ? (
+        <Slot id="year_built" textLeaf>
+          <p>Built {slots.year_built.slice(0, 4)}</p>
+        </Slot>
+      ) : null}
+    </Section>
+  );
+}
+```
+
+If the slot should never be absent, the other correct fix is in the schema — declare it
+`required: true`, and the type narrows to `string` everywhere.
+
+## See also
+
+- [The schema system](../schema-system.md#renderertsx--props-derived-never-hand-written) —
+  how `SectionProps` resolves each slot to its runtime type.
+- [`props-from-schema`](props-from-schema.md) — the rule that stops a hand-written `Props`
+  from disabling this inference in the first place.
+- [`render-invariant`](render-invariant.md) — the same class of bug caught at render time,
+  for the cases the types cannot see.