@port60/template-kit 0.7.0 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@port60/template-kit",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Build Port60 site templates locally: scaffold, live-preview, validate against the platform contract, and package for studio upload. AI-agent ready — every scaffold ships AGENTS.md and validate emits machine-readable JSON.",
   "type": "module",
   "bin": {

package/src/commands/create.mjs

@@ -3,6 +3,9 @@ import { resolve, join, basename } from 'node:path';
 import { agentsMd } from '../lib/agentsMd.mjs';
 
 const NAME_PATTERN = /^[a-z][a-z0-9-]{1,48}[a-z0-9]$/;
+const KIT_PACKAGE = JSON.parse(
+  readFileSync(resolve(import.meta.dirname, '../../package.json'), 'utf8')
+);
 
 /** `create <dir> [--name x] [--label "X"]` — a working, validating template from the starter,
  *  briefed for AI agents (AGENTS.md + CLAUDE.md) and wired with the kit's npm scripts. */
@@ -50,7 +53,7 @@ export function create(args) {
       package: 'p60-template-kit package .'
     },
     devDependencies: {
-      '@port60/template-kit': '^0.1.0'
+      '@port60/template-kit': `^${KIT_PACKAGE.version}`
     }
   }, null, 2) + '\n');
   writeFileSync(join(target, 'README.md'), `# ${label}

package/src/commands/dev.mjs

@@ -1,5 +1,5 @@
 import { createServer } from 'node:http';
-import { watch } from 'node:fs';
+import { watch, readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { renderStudioPreview } from '../vendor/validator/preview.mjs';
 import { validateArtifact } from '../vendor/validator/validate.mjs';
@@ -7,18 +7,45 @@ import { loadArtifactDir } from '../lib/artifactFiles.mjs';
 
 /**
  * `dev <dir> [--port 4400]` — the local preview: your template over the contract's kind fixtures,
- * the SAME render the studio and reviewers see (islands as placeholders, network-dead CSP).
- * Files are re-read on every request, so a browser refresh is the hot reload; file changes also
- * re-run validation into the terminal — the human watches the page, the agent watches the JSON.
+ * the SAME render the studio and reviewers see (islands as fixture-hydrated skeletons,
+ * network-dead CSP). ONE addition over the studio render: the platform's own behaviour runtime is
+ * inlined, so data-p60-* carousels, reveals and tabs run for real locally — the only script the
+ * document can execute. Files are re-read on every request, so a browser refresh is the hot
+ * reload; file changes also re-run validation into the terminal — the human watches the page,
+ * the agent watches the JSON.
  */
 export async function dev(args) {
   const dir = resolve(args._[0] ?? '.');
   const port = Number(args.port ?? 4400);
+  let behaviorsRuntime = null;
+  try {
+    behaviorsRuntime = readFileSync(
+      resolve(import.meta.dirname, '../vendor/validator/behaviors-runtime.js'), 'utf8');
+  } catch {
+    // An older vendored copy without the runtime — the preview degrades to the CSS approximation.
+  }
+
+  // The preview is ROUTED: nav links land on real surfaces, so an author sees every platform
+  // page wearing their chrome — their own page template where they ship one, the platform's
+  // fixture skeleton where the page is platform-owned (ticket purchase, donate, campaigns).
+  const surfaceFor = (rawUrl) => {
+    const url = new URL(rawUrl, 'http://preview.local');
+    const path = url.pathname.replace(/\/+$/, '') || '/';
+    if (path === '/events') return url.searchParams.has('event') ? 'event' : 'events';
+    if (path === '/services') return url.searchParams.has('service') ? 'service' : 'services';
+    if (path === '/donate') return 'donate';
+    if (path === '/articles' || path === '/articles/all') return 'articles';
+    if (path.startsWith('/articles/')) return 'article';
+    if (path === '/campaigns') return 'campaigns';
+    if (path.startsWith('/campaigns/')) return 'campaign';
+    if (path === '/courses') return 'course';
+    return 'home';
+  };
 
   const server = createServer(async (req, res) => {
     try {
       const files = loadArtifactDir(dir);
-      const html = await renderStudioPreview(files);
+      const html = await renderStudioPreview(files, { behaviorsRuntime, surface: surfaceFor(req.url ?? '/') });
       res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8', 'Cache-Control': 'no-store' });
       res.end(html);
     } catch (e) {
@@ -33,6 +60,17 @@ ${errors.length ? `<h2>Validation says</h2><ul>${errors.map((x) => `<li>${String
     }
   });
 
+  // A taken port is the most likely first-run failure (a forgotten dev server from another
+  // template), and a raw EADDRINUSE stack reads like the kit is broken. Name the fix instead.
+  server.on('error', (e) => {
+    if (e.code === 'EADDRINUSE') {
+      console.error(`✗ port ${port} is already in use — another preview is probably still running.`);
+      console.error(`  Stop it, or start this one elsewhere:  p60-template-kit dev ${args._[0] ?? '.'} --port ${port + 1}`);
+      process.exit(1);
+    }
+    throw e;
+  });
+
   server.listen(port, () => {
     console.log(`✓ preview at http://localhost:${port} — refresh after edits`);
     console.log('  watching for changes; validation runs on save:');

package/src/lib/agentsMd.mjs

@@ -53,9 +53,29 @@ platform accepts it; if it fails here, the upload will fail identically.
    hide the rail when \`worship\` is null, and rendering it undeclared is equally an error. The
    same honesty applies across the contract.
 5. **Render budgets are real.** Runaway loops are killed (~1s per render). Keep renderers simple.
-6. **Context is a whitelist.** Sections see \`{section, brand}\`; layouts see
-   \`{brand, nav, socials, worship}\`; page templates see their fixture + \`brand\`. Nothing else
-   exists — do not invent variables.
+6. **Context is a whitelist.** Sections see \`{section, brand}\` plus only the collection named by
+   that section in the contract; layouts see \`{brand, nav, socials, worship, locale}\`; page
+   templates see their documented fixture + \`brand\`. Nothing else exists — do not invent
+   variables.
+7. **Capabilities are matching metadata, never entitlements.** Every value in
+   \`requiresCapabilities\` must have a declared section, page template or island that presents it.
+   \`suitsProfiles\` describes design intent and changes catalogue ordering only.
+
+## What each declaration owns
+
+- \`supports.layout\` owns the visible header, navigation and footer around platform pages. The
+  platform still owns the document head, consent and identity.
+- \`supports.pages\` owns section based bodies for \`home\` and \`about\` through the declared
+  renderers in \`sections/\`.
+- \`supports.pageTemplates: ["events"]\` owns the events listing only. Event details, RSVP and
+  ticket purchase remain platform owned.
+- \`supports.pageTemplates: ["course"]\` owns a course detail presentation only. The course
+  listing stays platform owned and enrolment remains the \`course_enrol\` island.
+- \`supports.pageTemplates: ["articles"]\` owns the article front page and archive listings.
+- \`supports.pageTemplates: ["article"]\` owns article detail presentation; engagement and
+  comments stay the \`article_engagement\` and \`article_comments\` islands.
+- Other platform routes keep their platform body and render inside your layout. Capability flags
+  expose documented optional context; they do not transfer transaction or route ownership.
 
 ## What to build with
 
@@ -70,6 +90,15 @@ platform accepts it; if it fails here, the upload will fail identically.
   behaviourally.
 - "Looks" = named one-click bundles of knob values in \`manifest.looks\`.
 - Fonts: only families from the platform font catalogue, declared with the weights you use.
+- Navigation can contain two levels below a top item. Render every supplied child and branch on
+  optional \`group\`, \`description\`, \`imageUrl\` and \`megaMenu\` promo metadata. Never hardcode
+  menu groups that are not in \`nav\`.
+- Dynamic sections include appeals (\`causes\`), programmes (\`services\`), resources, locations,
+  volunteering opportunities and structured media. Derive or omit when a collection is empty and
+  use the supplied URLs rather than constructing routes.
+- Submission and behaviour surfaces such as \`newsletter_signup\`, \`volunteer_signup\`, \`form\`,
+  \`search\`, \`language_switch\` and \`next_prayer\` are platform islands. Place and style them;
+  never reproduce their API calls or consent behaviour.
 - \`manifest.imagery.hero\` (optional but recommended): declare the photo shape YOUR hero
   composes best with (\`idealAspect\`, \`minWidth\`, a one-line \`note\`) — the charity's editor
   measures their actual upload against it and advises. Advice, never enforcement.

package/src/vendor/contract/v1/behaviours.json

@@ -0,0 +1,129 @@
+{
+  "description": "The behaviour catalogue: engine-attached JavaScript a template opts into with data attributes on its own markup. Templates never ship code; they author complete static markup and declare behaviours in supports.behaviors. The engine adds the p60-js class to the root element when its script runs; any CSS that hides pre-behaviour content MUST be scoped under .p60-js so the no-JS render stays complete. All behaviours honour prefers-reduced-motion centrally. State classes are toggled by the engine; their appearance is entirely the template's CSS.",
+  "behaviours": [
+    {
+      "name": "reveal",
+      "status": "available",
+      "label": "Reveal on scroll",
+      "description": "Adds is-revealed when the element first enters the viewport; the template's CSS does the actual motion. data-p60-reveal-group on a container staggers its children by stamping --p60-reveal-index on each (use it in a transition-delay calc). Reduced motion: is-revealed applies immediately on load.",
+      "attributes": [
+        { "attr": "data-p60-reveal", "value": "optional variant name for the CSS to key on" },
+        { "attr": "data-p60-reveal-group", "value": "none; staggers direct children" }
+      ],
+      "stateClasses": ["is-revealed"],
+      "cssVars": ["--p60-reveal-index"]
+    },
+    {
+      "name": "counter",
+      "status": "available",
+      "label": "Animated counter",
+      "description": "Counts the element's number up from zero when first revealed. The static text IS the final formatted value (the no-JS render); data-p60-count carries the numeric target the engine animates to, grouped with the page locale. Reduced motion: the final number shows immediately.",
+      "attributes": [
+        { "attr": "data-p60-count", "value": "the numeric target, digits only" },
+        { "attr": "data-p60-count-duration", "value": "optional ms, capped at 4000 (default 1200)" }
+      ],
+      "stateClasses": ["is-revealed"],
+      "cssVars": []
+    },
+    {
+      "name": "progress",
+      "status": "available",
+      "label": "Progress bar sweep",
+      "description": "Animates the marked element's width from zero to its authored width when first revealed. The authored width (inline style or CSS) is the target and the no-JS render. Reduced motion: the authored width stands untouched.",
+      "attributes": [
+        { "attr": "data-p60-progress", "value": "none; the element's own width is the target" }
+      ],
+      "stateClasses": ["is-revealed"],
+      "cssVars": []
+    },
+    {
+      "name": "countdown",
+      "status": "available",
+      "label": "Countdown",
+      "description": "Replaces the element's content with a live compact remainder to data-p60-until (\"3d 12h 45m\"). The static content is the authored date text (the no-JS render). On expiry the engine adds is-elapsed and swaps to data-p60-elapsed-text when provided. Countdowns keep ticking under reduced motion: they are information, not decoration. v1 unit labels are compact and language-neutral (d/h/m/s).",
+      "attributes": [
+        { "attr": "data-p60-countdown", "value": "segments: dhms, dhm (default) or hm" },
+        { "attr": "data-p60-until", "value": "ISO-8601 instant, required" },
+        { "attr": "data-p60-elapsed-text", "value": "optional text shown once elapsed" }
+      ],
+      "stateClasses": ["is-elapsed"],
+      "cssVars": []
+    },
+    {
+      "name": "accordion",
+      "status": "available",
+      "label": "Accordion",
+      "description": "On a container of native details elements: exclusive-open (opening one closes the others) plus smooth height animation. data-p60-accordion=\"multi\" keeps independent opening. Built on details/summary so the no-JS render is already functional and semantics are free. Reduced motion: no height animation, instant toggle.",
+      "attributes": [
+        { "attr": "data-p60-accordion", "value": "none for exclusive-open; \"multi\" for independent" }
+      ],
+      "stateClasses": ["is-open"],
+      "cssVars": []
+    },
+    {
+      "name": "stickyHeader",
+      "status": "available",
+      "label": "Sticky header condense",
+      "description": "State classes for scroll-aware headers: past a small threshold the engine adds is-condensed; with the \"auto-hide\" value, scrolling down past 160px adds is-hidden and scrolling up removes it. The engine only ever toggles classes (rAF-throttled) — what condensing or hiding looks like, and whether it animates, is entirely the template's CSS (gate transitions behind prefers-reduced-motion yourself; the classes always apply because a condensed header is layout, not decoration).",
+      "attributes": [
+        { "attr": "data-p60-sticky-header", "value": "none for condense-only; \"auto-hide\" adds the hide-on-scroll-down pair" }
+      ],
+      "stateClasses": ["is-condensed", "is-hidden"],
+      "cssVars": []
+    },
+    {
+      "name": "stickyCta",
+      "status": "available",
+      "label": "Sticky call-to-action bar",
+      "description": "Adds is-stuck once the visitor scrolls past the threshold (the attribute value in px, default 480) and removes it above. The bar should DUPLICATE an action that already exists in the page (a donate button, a ticket link) — because of that, this is the one behaviour whose element may be hidden unconditionally in CSS rather than .p60-js-scoped: a no-JS visitor loses nothing, the original action is still on the page.",
+      "attributes": [
+        { "attr": "data-p60-sticky-cta", "value": "optional scroll threshold in px (default 480)" }
+      ],
+      "stateClasses": ["is-stuck"],
+      "cssVars": []
+    },
+    {
+      "name": "lightbox",
+      "status": "available",
+      "label": "Lightbox",
+      "description": "On a group container: each data-p60-lightbox-item is an anchor whose href is the full image (the no-JS render simply navigates to it — already functional). The engine intercepts the click and opens an injected overlay (.p60-lightbox) with the image, a caption from data-p60-caption or the thumbnail's alt, a close button, backdrop and Escape close, arrow-key prev/next within the group, and a focus trap. Reduced motion: no transition on the overlay (the engine sets none; style the steady state).",
+      "attributes": [
+        { "attr": "data-p60-lightbox", "value": "none; the group container" },
+        { "attr": "data-p60-lightbox-item", "value": "none; on each anchor to a full image" },
+        { "attr": "data-p60-caption", "value": "optional caption text on an item" }
+      ],
+      "stateClasses": ["is-open"],
+      "cssVars": [],
+      "injects": [".p60-lightbox", ".p60-lightbox-img", ".p60-lightbox-caption", ".p60-lightbox-close", ".p60-lightbox-prev", ".p60-lightbox-next"]
+    },
+    {
+      "name": "tabs",
+      "status": "available",
+      "label": "Tabs",
+      "description": "data-p60-tab=\"key\" on each tab control and data-p60-panel=\"key\" on each panel, inside a data-p60-tabs container. The engine wires the tablist/tab/tabpanel roles, aria-selected, roving tabindex, arrow/Home/End keys, toggles is-active on the active pair and hides inactive panels with the hidden attribute — so the no-JS render shows every panel stacked and complete, with no CSS scoping needed. The first tab (or the one authored with is-active) starts active.",
+      "attributes": [
+        { "attr": "data-p60-tabs", "value": "none; the container" },
+        { "attr": "data-p60-tab", "value": "the key of the panel this control activates" },
+        { "attr": "data-p60-panel", "value": "the key matching its control" }
+      ],
+      "stateClasses": ["is-active"],
+      "cssVars": []
+    },
+    {
+      "name": "carousel",
+      "status": "available",
+      "label": "Carousel",
+      "description": "On a container with one data-p60-slide per child: the engine manages is-active across slides, injects a dots nav (.p60-carousel-dots with one button per slide), wires optional template-provided data-p60-carousel-prev/data-p60-carousel-next controls, adds swipe, keyboard arrows, pause on hover and focus, and hides inactive slides from assistive tech. Value \"auto\" enables auto-advance (data-p60-interval ms, min 3000, default 6000); reduced motion disables auto-advance while controls keep working. The engine stamps --p60-carousel-index on the container for track-translate designs; class-based fade on is-active is the simplest pattern. CSS hiding non-active slides MUST be .p60-js-scoped so the no-JS render shows all slides.",
+      "attributes": [
+        { "attr": "data-p60-carousel", "value": "none for manual; \"auto\" for auto-advance" },
+        { "attr": "data-p60-slide", "value": "none; one per slide child" },
+        { "attr": "data-p60-interval", "value": "optional auto-advance ms, min 3000 (default 6000)" },
+        { "attr": "data-p60-carousel-prev", "value": "none; optional template-provided control" },
+        { "attr": "data-p60-carousel-next", "value": "none; optional template-provided control" }
+      ],
+      "stateClasses": ["is-active"],
+      "cssVars": ["--p60-carousel-index"],
+      "injects": [".p60-carousel-dots", ".p60-carousel-dot", ".p60-carousel-dot--active"]
+    }
+  ]
+}