@port60/template-kit 0.17.0 → 0.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@port60/template-kit",
-  "version": "0.17.0",
+  "version": "0.18.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/dev.mjs

@@ -132,7 +132,9 @@ export async function dev(args) {
         fixtureImageBase,
         previewContent,
         contentImageOrigins: imageOriginsOf(previewContent),
-        surface: surfaceFor(req.url ?? '/')
+        surface: surfaceFor(req.url ?? '/'),
+        // ?focus=donate|volunteer|none: what leads, so the hero shows each widget and its buttons.
+        focus: url.searchParams.get('focus') ?? undefined
       });
       res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8', 'Cache-Control': 'no-store' });
       res.end(html);

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

@@ -31,7 +31,7 @@
         "section",
         "layout"
       ],
-      "description": "What leads on the site: 'donate' (default) or 'volunteer'. The charity's one switch (docs/volunteering.md 'Site focus'); everything below follows from it."
+      "description": "What the primary_action_widget island becomes: 'donate' (default, the donation widget), 'volunteer' (the volunteer sign-up) or 'none' (the charity chose no widget in the hero). The charity's one switch (docs/volunteering.md 'Site focus'); everything below follows from it."
     },
     {
       "path": "site.actions",
@@ -46,7 +46,7 @@
       "availableIn": [
         "section"
       ],
-      "description": "homeHero only: the leading action { kind, label, href }, the same as site.actions.primary. Render it as a widget with {% island 'primary_action' %} when section.actionStyle is 'widget'."
+      "description": "homeHero only: the leading action { kind, label, href }, the same as site.actions.primary. Render it as a widget with {% island 'primary_action_widget' %} when section.actionStyle is 'widget'; that island becomes this action's widget."
     },
     {
       "path": "section.secondary",

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

@@ -283,10 +283,10 @@
       ]
     },
     {
-      "name": "primary_action",
-      "label": "Primary action",
+      "name": "primary_action_widget",
+      "label": "Primary action widget",
       "status": "available",
-      "description": "The composite for the site focus: mounts the donation widget or the volunteer sign-up according to what the charity chose to lead with (site.focus), so a template places one static island and the choice moves without a variable name. Both widgets wear .action-card; .donate-card and .volunteer-card carry kind-specific treatment. A template that wants a different layout per kind branches on section.primary.kind and places donation_widget or volunteer_signup directly.",
+      "description": "The widget that leads the site. It IS the donation widget when the charity chose giving to lead, the volunteer sign-up when volunteering leads, and nothing when the charity chose no widget in the hero; site.focus tells you which ('donate', 'volunteer' or 'none'). Place {% island 'primary_action_widget' %} in the home hero's widget slot INSTEAD of donation_widget whenever your template declares supports.focus: the platform decides which widget renders, the template never does, and the charity's switch moves it without a template change. Both widgets wear .action-card for shared treatment; .donate-card and .volunteer-card carry kind-specific styling. A template that wants a different layout per kind may branch on section.primary.kind and place donation_widget or volunteer_signup itself, but then it owns the switch.",
       "params": [],
       "stylingApi": [
         ".action-card",

package/src/vendor/contract/v1/manifest.schema.json

@@ -185,7 +185,7 @@
               "volunteer"
             ]
           },
-          "description": "The site-focus kinds this template can LEAD with (docs/volunteering.md). Declaring 'volunteer' means the home hero places the composite primary_action island (or branches on section.primary.kind), so the volunteer sign-up can take the widget slot; the picker marks templates that cannot lead with volunteering. Templates that predate the setting keep rendering the donation widget, since donate is the default."
+          "description": "The site-focus kinds this template can LEAD with (docs/volunteering.md). Declaring 'volunteer' means the home hero places the primary_action_widget island (the widget that becomes the donation widget or the volunteer sign-up as the charity chooses) or branches on section.primary.kind, so the volunteer sign-up can take the widget slot; the picker marks templates that cannot lead with volunteering. Templates that predate the setting keep rendering the donation widget, since donate is the default."
         }
       }
     },

package/src/vendor/validator/focus.mjs

@@ -0,0 +1,49 @@
+// The site focus for the PREVIEW: a JavaScript twin of charity-site's lib/focus.ts, kept in step by
+// hand (the validator is plain JS and is vendored into the kit). Same rules: the leading action is
+// the widget in the hero; the other action is the one button in the header and beside the hero; the
+// leading action never appears twice. The preview assumes volunteering is OPEN, so the pairing shows.
+export const FOCUS_CHOICES = ['donate', 'volunteer', 'none'];
+
+const ACTION = {
+  donate: { kind: 'donate', label: 'Donate', href: '/donate' },
+  volunteer: { kind: 'volunteer', label: 'Volunteer', href: '/volunteer' }
+};
+
+/** `?focus=` from the dev server, or nothing: 'donate' is the platform default. */
+export function normaliseFocus(value) {
+  return FOCUS_CHOICES.includes(value) ? value : 'donate';
+}
+
+/** The resolved surfaces for one preview render, the shape of site.actions on a live site. */
+export function previewActions(focus) {
+  if (focus === 'volunteer') {
+    return { primary: ACTION.volunteer, secondary: ACTION.donate, widget: 'volunteer', header: ACTION.donate, hero: ACTION.donate };
+  }
+  if (focus === 'none') {
+    // Buttons only (a Custom setting with no widget): the hero button leads with giving.
+    return { primary: ACTION.donate, secondary: ACTION.volunteer, widget: null, header: ACTION.donate, hero: ACTION.donate };
+  }
+  return { primary: ACTION.donate, secondary: ACTION.volunteer, widget: 'donate', header: ACTION.volunteer, hero: ACTION.volunteer };
+}
+
+/** The home hero's resolved fields, as the platform computes them (lib/focus.ts withResolvedActions). */
+export function withResolvedActions(content, actions) {
+  const style = content.actionStyle ?? content.givingStyle;
+  const buttonMode = style === 'button' || actions.widget === null;
+  return {
+    ...content,
+    actionStyle: buttonMode ? 'button' : 'widget',
+    primary: actions.primary,
+    secondary: actions.secondary,
+    action: buttonMode && actions.hero === null && style === 'button' ? actions.primary : actions.hero
+  };
+}
+
+/** The site tree with the focus applied: site.focus, site.actions, and the nav's one button. */
+export function applyFocus(site, actions) {
+  const swapCta = (items) => Array.isArray(items)
+    ? items.map((item) => (item && item.cta ? (actions.header ? { ...item, label: actions.header.label, href: actions.header.href } : null) : item)).filter(Boolean)
+    : items;
+  const nav = site.nav ? { ...site.nav, items: swapCta(site.nav.items), derived: swapCta(site.nav.derived) } : site.nav;
+  return { ...site, focus: actions.widget ?? 'none', actions, nav };
+}

package/src/vendor/validator/preview.mjs

@@ -17,6 +17,7 @@ import islandRegistry from '../contract/v1/islands.json' with { type: 'json' };
 import contextContract from '../contract/v1/context.json' with { type: 'json' };
 import { resolveFixtureArt } from './fixture-art.mjs';
 import { buildSiteFixture, applyPreviewContent } from './site-context.mjs';
+import { normaliseFocus, previewActions, withResolvedActions, applyFocus } from './focus.mjs';
 
 // Fixture imagery resolved for the SEALED studio render (p60fixture: refs become inline-SVG data
 // URIs the network-dead CSP can show). The dev preview may instead resolve them to the platform
@@ -143,8 +144,16 @@ function islandSkeleton(name, ctx = {}, fx = STUDIO_FX) {
         <label class="newsletter-label">Email address</label><div class="newsletter-fields"><input class="newsletter-email" type="email" disabled><button class="newsletter-submit" type="button" disabled>Join our newsletter</button></div>
         <label class="newsletter-consent"><input type="checkbox" disabled><span>Email me about our work and appeals.</span></label>
       </form>`;
-    case 'primary_action':
-      return islandSkeleton('donation_widget', ctx, fx).replace('data-p60-preview-island="donation_widget"', 'data-p60-preview-island="primary_action"');
+    case 'primary_action_widget':
+      // What this island becomes follows the preview's focus (fixtures.focus, from ?focus= on the
+      // dev server): the volunteer sign-up, nothing, or the default, the donation widget.
+      if (fixtures.focus === 'volunteer') {
+        return islandSkeleton('volunteer_signup', ctx, fx).replace('data-p60-preview-island="volunteer_signup"', 'data-p60-preview-island="primary_action_widget"');
+      }
+      if (fixtures.focus === 'none') {
+        return `<div class="p60-preview-empty" data-p60-preview-island="primary_action_widget">${previewNote(name)}<p>No widget here: this charity leads with buttons only (site.focus is 'none').</p></div>`;
+      }
+      return islandSkeleton('donation_widget', ctx, fx).replace('data-p60-preview-island="donation_widget"', 'data-p60-preview-island="primary_action_widget"');
     case 'volunteer_signup':
       return `<section class="donate-card vol-card" data-p60-preview-island="volunteer_signup">
         ${previewNote(name)}
@@ -359,18 +368,27 @@ const SURFACES = {
 /** The routed dev preview's surface names (plus 'home'). */
 export const PREVIEW_SURFACES = ['home', ...Object.keys(SURFACES)];
 
-function surfaceBar(active) {
+function surfaceBar(active, focus = 'donate') {
+  const withFocus = (href) => (focus === 'donate' ? href : `${href}${href.includes('?') ? '&' : '?'}focus=${focus}`);
   const link = (name, href) =>
-    `<a href="${href}"${name === active ? ' style="font-weight:700;text-decoration:underline"' : ''}>${name}</a>`;
+    `<a href="${withFocus(href)}"${name === active ? ' style="font-weight:700;text-decoration:underline"' : ''}>${name}</a>`;
   const links = [
     link('home', '/'), link('events', '/events'), link('event', '/events?event=fixture'),
     link('services', '/services'), link('service', '/services?service=fixture'),
     link('donate', '/donate'), link('articles', '/articles'), link('article', '/articles/fixture'),
     link('campaigns', '/campaigns'), link('campaign', '/campaigns/fixture'), link('course', '/courses'),
-    `<a href="/model" style="margin-left:auto;font-weight:700">site.content model →</a>`,
+    `<a href="${withFocus('/model')}" style="margin-left:auto;font-weight:700">site.content model →</a>`,
   ];
+  // What leads: the charity's switch, here as three links, so a developer sees the hero widget as
+  // the donation widget, as the volunteer sign-up, or absent, with the buttons following each time.
+  const focusLink = (value, label) =>
+    `<a href="${value === 'donate' ? '/' : `/?focus=${value}`}"${value === focus ? ' style="font-weight:700;text-decoration:underline"' : ''}>${label}</a>`;
+  const focusLinks = [focusLink('donate', 'giving'), focusLink('volunteer', 'volunteering'), focusLink('none', 'buttons only')];
   return `<nav class="p60-preview-surfaces" aria-label="Preview surfaces" style="position:sticky;top:0;z-index:99;display:flex;gap:12px;flex-wrap:wrap;padding:8px 14px;font:12px/1.4 system-ui,sans-serif;background:#0b1220;color:#e6e9f2;opacity:.94">
     <strong style="letter-spacing:.06em;text-transform:uppercase;font-size:10px">Surfaces</strong>${links.join('')}
+    <span style="flex-basis:100%;height:0"></span>
+    <strong style="letter-spacing:.06em;text-transform:uppercase;font-size:10px">Leads with</strong>${focusLinks.join('')}
+    <span style="opacity:.7">the hero widget becomes the donation widget, the volunteer sign-up, or nothing; the buttons follow</span>
   </nav>`;
 }
 
@@ -420,12 +438,17 @@ export async function renderStudioPreview(files, options = {}) {
   // imagery to the platform CDN instead of inline-SVG art (the dev-richer half of the split).
   const artOptions = options.fixtureImageBase ? { imageBase: options.fixtureImageBase } : null;
   let fx = artOptions ? resolveFixtureArt(contextContract.fixtures, artOptions) : STUDIO_FX;
+  // What leads (docs/volunteering.md 'Site focus'): the dev server passes ?focus=; the studio
+  // renders the platform default. The island skeletons read it from the fixtures they are handed.
+  const focus = normaliseFocus(options.focus);
+  const actions = previewActions(focus);
+  fx = { ...fx, focus };
   // The one content tree (content model v1): about composed from this manifest's declared
   // sections, dev preview-content overlaid when the kit passes it (validated there), imagery
   // resolved exactly like the rest of the fixtures.
-  const site = resolveFixtureArt(
+  const site = applyFocus(resolveFixtureArt(
     applyPreviewContent(buildSiteFixture(manifest), options.previewContent ?? null),
-    artOptions ?? {});
+    artOptions ?? {}), actions);
   const brand = site.brand ?? fx.brand;
   // With a content override, the TREE is the source of truth for every fixture view: the routed
   // platform skeletons and island skeletons re-derive their slices from the overridden site, so
@@ -481,8 +504,12 @@ export async function renderStudioPreview(files, options = {}) {
       const entry = catalogueByType.get(type);
       const source = files[`sections/${type}.liquid`];
       if (!entry || source == null) continue;
+      const sample = artOptions ? resolveFixtureArt(entry.sample ?? {}, artOptions) : resolveFixtureArt(entry.sample ?? {});
       const context = {
-        section: artOptions ? resolveFixtureArt(entry.sample ?? {}, artOptions) : resolveFixtureArt(entry.sample ?? {}),
+        // The home hero carries the resolved actions exactly as the platform hands them over, so a
+        // developer sees the widget AND the button that pairs with it. The catalogue sample's
+        // givingStyle is dropped here: in the preview the focus decides the style.
+        section: type === 'homeHero' ? withResolvedActions({ ...sample, givingStyle: undefined, actionStyle: undefined }, actions) : sample,
         brand,
         site,
         ...(fx.sections?.[type] ?? {})
@@ -580,7 +607,7 @@ export async function renderStudioPreview(files, options = {}) {
 <style>${themeCss}</style>
 </head>
 <body ${attrs}>
-${options.surface ? surfaceBar(surface) : ''}
+${options.surface ? surfaceBar(surface, focus) : ''}
 ${bodyHtml}
 ${runtime ? `<script>${runtime}\np60Behaviors.initBehaviors();</script>` : ''}
 </body>

package/src/vendor/validator/validate.mjs

@@ -100,7 +100,7 @@ export async function validateArtifact(files) {
       newsletter: () => islands.has('newsletter_signup'),
       i18n: () => islands.has('language_switch'),
       search: () => islands.has('search'),
-      volunteering: () => islands.has('volunteer_signup') || islands.has('primary_action')
+      volunteering: () => islands.has('volunteer_signup') || islands.has('primary_action_widget')
     };
     for (const capability of manifest?.requiresCapabilities ?? []) {
       if (!capabilitySurface[capability]?.()) {
@@ -110,14 +110,15 @@ export async function validateArtifact(files) {
   }
 
   // Site focus honesty (docs/volunteering.md): a template that claims it can lead with
-  // volunteering must give the volunteer sign-up a way into the hero, either the composite
-  // primary_action island or the volunteer_signup island placed directly.
+  // volunteering must give the volunteer sign-up a way into the hero, either the
+  // primary_action_widget island (which becomes the sign-up when volunteering leads) or the
+  // volunteer_signup island placed directly.
   {
     const focusKinds = new Set(manifest?.supports?.focus ?? []);
     if (focusKinds.has('volunteer')) {
       const liquidSource = Object.entries(files).filter(([path]) => path.endsWith('.liquid')).map(([, s]) => s).join('\n');
-      if (!/island\s+['"]primary_action['"]/.test(liquidSource) && !/island\s+['"]volunteer_signup['"]/.test(liquidSource)) {
-        errors.push("manifest: supports.focus lists 'volunteer' but no section places {% island 'primary_action' %} (or 'volunteer_signup'), so the site could never lead with volunteering");
+      if (!/island\s+['"]primary_action_widget['"]/.test(liquidSource) && !/island\s+['"]volunteer_signup['"]/.test(liquidSource)) {
+        errors.push("manifest: supports.focus lists 'volunteer' but no section places {% island 'primary_action_widget' %} (or 'volunteer_signup'), so the site could never lead with volunteering");
       }
     }
   }

package/starter/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "starter",
-  "version": "1.11.0",
+  "version": "1.12.0",
   "format": "port60-liquid@1",
   "label": "Starter",
   "description": "The reference template for the Port60 dialect, the developer docs' worked example and the base to copy when building your own. 1.1.0 adds the layout slot: the template owns the header, navigation and footer chrome.",
@@ -23,7 +23,7 @@
       "member_menu",
       "hero_carousel",
       "map",
-      "primary_action"
+      "primary_action_widget"
     ],
     "layout": true,
     "heroImagery": true,

package/starter/sections/homeHero.liquid

@@ -68,8 +68,8 @@
       </div>
     </div>
     <aside id="donate">
-      {%- comment -%} The site focus decides which widget leads (section.primary); the composite island mounts it. {%- endcomment -%}
-      {% island 'primary_action' %}
+      {%- comment -%} The site focus decides which widget leads (section.primary); this island becomes it: the donation widget or the volunteer sign-up. {%- endcomment -%}
+      {% island 'primary_action_widget' %}
     </aside>
   </div>
 </section>
@@ -108,7 +108,7 @@
     </div>
     {% unless section.actionStyle == 'button' or section.givingStyle == 'button' %}
     <aside id="donate">
-      {% island 'primary_action' %}
+      {% island 'primary_action_widget' %}
     </aside>
     {% endunless %}
   </div>