@port60/template-kit 0.16.0 → 0.18.0

package/src/vendor/validator/platform-base.css

@@ -2579,6 +2579,300 @@ textarea.p60-form-control {
   border-color: var(--primary-strong);
 }
 
+/* ---- Volunteer sign-up widget (components/VolunteerWidget.tsx) ----
+   Reuses the donate card vocabulary (.donate-card/.donate-head/.field/.donate-submit/.donate-success)
+   so a themed donate card themes this too; vol-* covers what is specific to asking for help. */
+.vol-search input,
+.vol-form input:not([type='checkbox']):not([type='radio']),
+.vol-form select,
+.vol-form textarea {
+  width: 100%;
+  border: 1.5px solid var(--line);
+  border-radius: 12px;
+  padding: 0.7rem 0.85rem;
+  font: inherit;
+  line-height: 1.45;
+  color: var(--ink);
+  background: var(--surface);
+}
+
+.vol-search input:focus,
+.vol-form input:not([type='checkbox']):not([type='radio']):focus,
+.vol-form select:focus,
+.vol-form textarea:focus {
+  outline: none;
+  border-color: var(--primary);
+  box-shadow: 0 0 0 3px var(--primary-soft);
+}
+
+/* The steps live in a body of ONE height (owner rule: the hero widget must not grow and jump
+   between steps). Lists scroll inside it; a step shorter than the body leaves quiet space. */
+.vol-body {
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+}
+
+.vol-body--list {
+  height: 32rem;
+  overflow: hidden;
+}
+
+.vol-body--form {
+  min-height: 32rem;
+}
+
+.vol-list {
+  display: grid;
+  gap: 0.6rem;
+  align-content: start;
+  flex: 1 1 auto;
+  min-height: 0;
+  overflow-y: auto;
+  padding-right: 0.2rem;
+  scrollbar-gutter: stable;
+}
+
+.vol-body > .vol-form,
+.vol-body > .vol-chosen,
+.vol-body > .vol-search {
+  flex: none;
+}
+
+.vol-group {
+  display: grid;
+  gap: 0.5rem;
+}
+
+.vol-group-label {
+  margin: 0.2rem 0 0;
+  font-size: 0.78rem;
+  font-weight: 700;
+  letter-spacing: 0.06em;
+  text-transform: uppercase;
+  color: var(--muted);
+}
+
+.vol-option {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.8rem;
+  width: 100%;
+  text-align: start;
+  border: 1.5px solid var(--line);
+  background: var(--surface);
+  color: var(--ink);
+  border-radius: 12px;
+  padding: 0.85rem 1rem;
+  font: inherit;
+  cursor: pointer;
+  transition: border-color 0.16s ease, background 0.16s ease;
+}
+
+.vol-option:hover,
+.vol-option:focus-visible {
+  border-color: var(--primary);
+  background: var(--primary-soft);
+  outline: none;
+}
+
+.vol-option-main {
+  display: grid;
+  gap: 0.15rem;
+  min-width: 0;
+}
+
+.vol-option-summary {
+  font-size: 0.88rem;
+  color: var(--muted);
+  line-height: 1.35;
+}
+
+.vol-option-meta {
+  display: grid;
+  gap: 0.2rem;
+  justify-items: end;
+  flex-shrink: 0;
+  text-align: end;
+}
+
+.vol-needed {
+  font-size: 0.8rem;
+  font-weight: 700;
+  color: var(--primary-strong);
+  white-space: nowrap;
+}
+
+.vol-needed.is-full {
+  color: var(--muted);
+}
+
+.vol-shift-count {
+  font-size: 0.78rem;
+  color: var(--muted);
+  white-space: nowrap;
+}
+
+.vol-chosen {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.8rem;
+  padding: 0.7rem 0.9rem;
+  border-radius: 12px;
+  background: var(--primary-soft);
+  font-size: 0.92rem;
+}
+
+.vol-chosen-shift {
+  display: block;
+  color: var(--muted);
+  font-size: 0.85rem;
+}
+
+.vol-form {
+  display: grid;
+  gap: 0.9rem;
+}
+
+.vol-optional {
+  font-style: normal;
+  font-weight: 500;
+  color: var(--muted);
+}
+
+.vol-availability {
+  border: 0;
+  padding: 0;
+  margin: 0;
+}
+
+.vol-availability legend {
+  font-weight: 600;
+  font-size: 0.9rem;
+  line-height: 1.4;
+  padding: 0;
+  margin-bottom: 0.4rem;
+}
+
+/* The When row is a select or a chip row; both sit on the same box height so the panel never
+   changes height when the choice above changes. */
+.vol-form select,
+.vol-chip {
+  box-sizing: border-box;
+  min-height: 3.1rem;
+}
+
+.vol-form .field > span {
+  line-height: 1.4;
+}
+
+.vol-chips {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.4rem;
+}
+
+.vol-summary-needed {
+  color: var(--primary-strong);
+  font-weight: 700;
+  text-transform: capitalize;
+}
+
+.vol-chip {
+  flex: 1 1 0;
+  border: 1.5px solid var(--line);
+  background: var(--surface);
+  color: var(--ink);
+  border-radius: 999px;
+  /* The same vertical rhythm as a select in this form, so the When row never changes height. */
+  padding: 0.7rem 0.4rem;
+  font: inherit;
+  font-size: 0.86rem;
+  line-height: 1.45;
+  font-weight: 600;
+  cursor: pointer;
+  white-space: nowrap;
+}
+
+.vol-chip.selected {
+  border-color: var(--primary);
+  background: var(--primary);
+  color: #fff;
+}
+
+
+.vol-why {
+  text-align: center;
+}
+
+.vol-form select {
+  appearance: none;
+  -webkit-appearance: none;
+  padding-right: 2.4rem;
+  background-image: url("data:image/svg+xml;charset=utf-8,%3Csvg xmlns='http://www.w3.org/2000/svg' width='12' height='8' viewBox='0 0 12 8'%3E%3Cpath d='M1 1l5 5 5-5' fill='none' stroke='%23555' stroke-width='1.8' stroke-linecap='round'/%3E%3C/svg%3E");
+  background-repeat: no-repeat;
+  background-position: right 0.9rem center;
+}
+
+.vol-form select:disabled {
+  opacity: 0.6;
+}
+
+.vol-summary {
+  margin: -0.3rem 0 0;
+  font-size: 0.86rem;
+  line-height: 1.4;
+  min-height: calc(0.86rem * 1.4 * 2);
+  color: var(--muted);
+  display: -webkit-box;
+  -webkit-line-clamp: 2;
+  -webkit-box-orient: vertical;
+  overflow: hidden;
+}
+
+.vol-field-error {
+  display: block;
+  font-style: normal;
+  font-size: 0.8rem;
+  line-height: 1.3;
+  color: var(--danger, #b3261e);
+}
+
+.vol-form .field.has-error input,
+.vol-form .field.has-error select {
+  border-color: var(--danger, #b3261e);
+}
+
+.vol-signed-in {
+  margin: 0;
+}
+
+.vol-extra {
+  display: grid;
+  gap: 0.9rem;
+  padding: 0.9rem;
+  border: 1px dashed var(--line);
+  border-radius: 12px;
+}
+
+.vol-extra .p60-form-heading {
+  margin: 0;
+  font-size: 1rem;
+}
+
+@media (max-width: 560px) {
+  .vol-option {
+    flex-direction: column;
+    align-items: stretch;
+  }
+  .vol-option-meta {
+    justify-items: start;
+    text-align: start;
+  }
+}
+
 /* ---- Members area (shell + sections; see components/members/) ----
    Desktop: left rail + content. Small screens: the rail becomes a horizontal, scrollable pill
    strip above the content — same registry, no separate mobile markup. */

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,6 +144,25 @@ 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_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)}
+        <header class="donate-head"><h2>Volunteer with us</h2><p class="donate-sub">Where would you like to help?</p></header>
+        <div class="vol-list">
+          <div class="vol-group"><p class="vol-group-label">General</p><button class="vol-option" type="button" disabled><span class="vol-option-main"><strong>Help out where needed</strong><span class="vol-option-summary">A few hours a month, wherever the team needs a hand.</span></span><span class="vol-option-meta"><span class="vol-needed">Everyone welcome</span></span></button></div>
+          <div class="vol-group"><p class="vol-group-label">Events</p><button class="vol-option" type="button" disabled><span class="vol-option-main"><strong>Spring fair stewards</strong><span class="vol-option-summary">Welcome visitors and keep the day running.</span></span><span class="vol-option-meta"><span class="vol-needed">6 volunteers needed</span><span class="vol-shift-count">3 shifts</span></span></button></div>
+        </div>
+      </section>`;
     case 'language_switch':
       return `<label class="language-switch" data-p60-preview-island="language_switch">${previewNote(name)}<span class="language-switch-label">Language</span><select class="language-switch-select" disabled><option>English</option><option>Cymraeg</option><option>العربية</option></select></label>`;
     case 'search':
@@ -348,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>`;
 }
 
@@ -409,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
@@ -470,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] ?? {})
@@ -569,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

@@ -99,7 +99,8 @@ export async function validateArtifact(files) {
       locations: () => sections.has('locations'),
       newsletter: () => islands.has('newsletter_signup'),
       i18n: () => islands.has('language_switch'),
-      search: () => islands.has('search')
+      search: () => islands.has('search'),
+      volunteering: () => islands.has('volunteer_signup') || islands.has('primary_action_widget')
     };
     for (const capability of manifest?.requiresCapabilities ?? []) {
       if (!capabilitySurface[capability]?.()) {
@@ -108,6 +109,20 @@ 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
+  // 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_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");
+      }
+    }
+  }
+
   // Markup and attributes, NEVER code — the machine-enforced JavaScript ban over every liquid
   // source (docs/template-behaviours.md). Behaviour is engine-owned; a template wanting motion
   // declares supports.behaviors and uses the data-p60-* grammar.

package/starter/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "starter",
-  "version": "1.10.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.",
@@ -22,13 +22,18 @@
       "donation_widget",
       "member_menu",
       "hero_carousel",
-      "map"
+      "map",
+      "primary_action_widget"
     ],
     "layout": true,
     "heroImagery": true,
     "behaviors": [
       "reveal",
       "carousel"
+    ],
+    "focus": [
+      "donate",
+      "volunteer"
     ]
   },
   "settings": {

package/starter/sections/homeHero.liquid

@@ -31,7 +31,7 @@
 {% endif %}
 {% assign heroFraming = section.photoFraming | default: 'fill' %}
 {% if heroCount > 0 and heroFraming == 'whole' %}
-{% if section.givingStyle == 'button' %}
+{% if section.actionStyle == 'button' or section.givingStyle == 'button' %}
 <section class="lq-homehero lq-homehero--vista{% if heroCount > 1 %} lq-homehero--carousel{% endif %}">
   <div class="lq-vista">
     <img class="lq-vista-sizer" src="{{ section.images.first.imageUrl }}" alt="{{ section.images.first.alt }}" style="object-position: {{ heroFocus }}" fetchpriority="high" decoding="async">
@@ -63,12 +63,13 @@
       <h1>{{ section.title | default: site.brand.tagline | default: site.brand.name }}</h1>
       {% if section.lead %}<p class="lq-homehero-lead">{{ section.lead }}</p>{% endif %}
       <div class="lq-homehero-actions">
-        <a class="button button-primary" href="#donate">{{ section.primaryLabel | default: 'Donate now' }}</a>
+        {% if section.action or section.primaryLabel %}<a class="button button-primary" href="{{ section.primaryHref | default: section.action.href | default: '#donate' }}">{{ section.primaryLabel | default: section.action.label | default: 'Donate now' }}</a>{% endif %}
         <a class="button" href="{{ section.secondaryHref | default: '/about' }}">{{ section.secondaryLabel | default: 'Our story' }}</a>
       </div>
     </div>
     <aside id="donate">
-      {% island 'donation_widget' %}
+      {%- 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>
@@ -97,17 +98,17 @@
       <h1>{{ section.title | default: site.brand.tagline | default: site.brand.name }}</h1>
       {% if section.lead %}<p class="lq-homehero-lead">{{ section.lead }}</p>{% endif %}
       <div class="lq-homehero-actions">
-        {% if section.givingStyle == 'button' %}
-        <a class="button button-primary" href="{{ section.primaryHref | default: '/donate' }}">{{ section.primaryLabel | default: 'Donate now' }}</a>
+        {% if section.actionStyle == 'button' or section.givingStyle == 'button' %}
+        {% if section.action or section.primaryLabel %}<a class="button button-primary" href="{{ section.primaryHref | default: section.action.href | default: '/donate' }}">{{ section.primaryLabel | default: section.action.label | default: 'Donate now' }}</a>{% endif %}
         {% else %}
-        <a class="button button-primary" href="#donate">{{ section.primaryLabel | default: 'Donate now' }}</a>
+        {% if section.action or section.primaryLabel %}<a class="button button-primary" href="{{ section.primaryHref | default: section.action.href | default: '#donate' }}">{{ section.primaryLabel | default: section.action.label | default: 'Donate now' }}</a>{% endif %}
         {% endif %}
         <a class="button" href="{{ section.secondaryHref | default: '/about' }}">{{ section.secondaryLabel | default: 'Our story' }}</a>
       </div>
     </div>
-    {% unless section.givingStyle == 'button' %}
+    {% unless section.actionStyle == 'button' or section.givingStyle == 'button' %}
     <aside id="donate">
-      {% island 'donation_widget' %}
+      {% island 'primary_action_widget' %}
     </aside>
     {% endunless %}
   </div>