@port60/template-kit 0.16.0 → 0.18.0

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

@@ -8,6 +8,7 @@
       "description": "The full donation flow for the tenant's quick-give cause: suggested amounts, custom amount, donor details, Gift Aid opt-in, payment. All payment/compliance behaviour is platform-owned.",
       "params": [],
       "stylingApi": [
+        ".action-card",
         ".donate-card",
         ".donate-head",
         ".donate-sub",
@@ -243,6 +244,55 @@
         ".impact-map-card-cta",
         ".impact-map-empty"
       ]
+    },
+    {
+      "name": "volunteer_signup",
+      "label": "Volunteer sign-up",
+      "status": "preview",
+      "description": "The volunteer sign-up flow: what to help with (general, then the events and campaigns that need people), when (only when the opportunity runs in shifts), a few details, then confirmation by a charity-branded email that also signs the volunteer in. Shares the donation widget's card vocabulary so a themed donate card themes this too; the vol-* classes cover what is specific to asking for help.",
+      "params": [],
+      "stylingApi": [
+        ".donate-card",
+        ".action-card",
+        ".vol-body",
+        ".volunteer-card",
+        ".vol-card",
+        ".vol-chosen",
+        ".vol-search",
+        ".vol-list",
+        ".vol-group",
+        ".vol-group-label",
+        ".vol-option",
+        ".vol-option-main",
+        ".vol-option-summary",
+        ".vol-option-meta",
+        ".vol-needed",
+        ".vol-shift-count",
+        ".vol-form",
+        ".vol-availability",
+        ".vol-chips",
+        ".vol-chip",
+        ".vol-confirm",
+        ".vol-optional",
+        ".vol-why",
+        ".vol-extra",
+        ".vol-summary",
+        ".vol-signed-in",
+        ".vol-summary-needed",
+        ".vol-field-error"
+      ]
+    },
+    {
+      "name": "primary_action_widget",
+      "label": "Primary action widget",
+      "status": "available",
+      "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",
+        ".donate-card",
+        ".volunteer-card"
+      ]
     }
   ]
 }

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

@@ -4,7 +4,12 @@
   "title": "Port60 template manifest (contract v1)",
   "type": "object",
   "additionalProperties": false,
-  "required": ["name", "version", "format", "supports"],
+  "required": [
+    "name",
+    "version",
+    "format",
+    "supports"
+  ],
   "properties": {
     "name": {
       "type": "string",
@@ -18,11 +23,20 @@
     },
     "format": {
       "type": "string",
-      "enum": ["port60-liquid@1"],
+      "enum": [
+        "port60-liquid@1"
+      ],
       "description": "The dialect/contract major this template is written against."
     },
-    "label": { "type": "string", "maxLength": 60, "description": "Human-readable name shown in pickers." },
-    "description": { "type": "string", "maxLength": 300 },
+    "label": {
+      "type": "string",
+      "maxLength": 60,
+      "description": "Human-readable name shown in pickers."
+    },
+    "description": {
+      "type": "string",
+      "maxLength": 300
+    },
     "requiresCapabilities": {
       "type": "array",
       "items": {
@@ -52,7 +66,15 @@
       "type": "array",
       "items": {
         "type": "string",
-        "enum": ["general", "mosque", "church", "appeal-charity", "pta", "community", "training"]
+        "enum": [
+          "general",
+          "mosque",
+          "church",
+          "appeal-charity",
+          "pta",
+          "community",
+          "training"
+        ]
       },
       "uniqueItems": true,
       "default": [],
@@ -66,25 +88,38 @@
     "supports": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["pages", "sections"],
+      "required": [
+        "pages",
+        "sections"
+      ],
       "properties": {
         "pages": {
           "type": "array",
-          "items": { "type": "string", "enum": ["home", "about"] },
+          "items": {
+            "type": "string",
+            "enum": [
+              "home",
+              "about"
+            ]
+          },
           "minItems": 1,
           "uniqueItems": true,
           "description": "Section based page bodies this template renders from sections/{type}.liquid. Contract v1 supports home and about. This is independent of layout chrome and route-specific pageTemplates."
         },
         "sections": {
           "type": "array",
-          "items": { "type": "string" },
+          "items": {
+            "type": "string"
+          },
           "minItems": 1,
           "uniqueItems": true,
           "description": "Section types this template ships renderers for (sections/{type}.liquid). Unsupported types are omitted at render, never an error."
         },
         "islands": {
           "type": "array",
-          "items": { "type": "string" },
+          "items": {
+            "type": "string"
+          },
           "uniqueItems": true,
           "default": [],
           "description": "Islands this template places. Every {% island %} name must be listed here AND exist in the platform island registry."
@@ -96,7 +131,15 @@
         },
         "pageTemplates": {
           "type": "array",
-          "items": { "type": "string", "enum": ["events", "course", "articles", "article"] },
+          "items": {
+            "type": "string",
+            "enum": [
+              "events",
+              "course",
+              "articles",
+              "article"
+            ]
+          },
           "uniqueItems": true,
           "default": [],
           "description": "Route-specific data views rendered from pages/{page}.liquid with documented context. Events and articles own listings; course and article own detail presentation. Event transactions, course enrolment, article engagement, comments, identity and consent stay platform-owned islands. Requires supports.layout; without an entry the platform body renders inside the template chrome."
@@ -115,10 +158,34 @@
           "type": "array",
           "items": {
             "type": "string",
-            "enum": ["reveal", "counter", "progress", "countdown", "accordion", "carousel", "stickyHeader", "stickyCta", "lightbox", "tabs", "nav"]
+            "enum": [
+              "reveal",
+              "counter",
+              "progress",
+              "countdown",
+              "accordion",
+              "carousel",
+              "stickyHeader",
+              "stickyCta",
+              "lightbox",
+              "tabs",
+              "nav"
+            ]
           },
           "uniqueItems": true,
           "description": "Engine-attached behaviours this template's markup opts into via data-p60-* attributes (see the behaviour catalogue). Templates never ship JavaScript; declaring here is what makes the engine wire the markup, and the validator proves declaration and usage agree in both directions."
+        },
+        "focus": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "enum": [
+              "donate",
+              "volunteer"
+            ]
+          },
+          "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."
         }
       }
     },
@@ -130,7 +197,10 @@
         "hero": {
           "type": "object",
           "additionalProperties": false,
-          "required": ["idealAspect", "minWidth"],
+          "required": [
+            "idealAspect",
+            "minWidth"
+          ],
           "properties": {
             "idealAspect": {
               "type": "string",
@@ -166,7 +236,10 @@
       "items": {
         "type": "object",
         "additionalProperties": false,
-        "required": ["name", "values"],
+        "required": [
+          "name",
+          "values"
+        ],
         "properties": {
           "name": {
             "type": "string",
@@ -176,14 +249,18 @@
           "values": {
             "type": "object",
             "minProperties": 1,
-            "propertyNames": { "pattern": "^[a-zA-Z][a-zA-Z0-9]{0,39}$" },
-            "additionalProperties": { "type": "string" },
-            "description": "Knob key → value. Every key must be a declared settings knob; select values must be listed options; font values must be catalogue families."
+            "propertyNames": {
+              "pattern": "^[a-zA-Z][a-zA-Z0-9]{0,39}$"
+            },
+            "additionalProperties": {
+              "type": "string"
+            },
+            "description": "Knob key \u2192 value. Every key must be a declared settings knob; select values must be listed options; font values must be catalogue families."
           }
         }
       },
       "default": [],
-      "description": "One-click LOOKS: author-named bundles of knob values (scheme + fonts + width…) applied together. Everything remains individually adjustable afterwards."
+      "description": "One-click LOOKS: author-named bundles of knob values (scheme + fonts + width\u2026) applied together. Everything remains individually adjustable afterwards."
     },
     "settings": {
       "type": "object",
@@ -194,21 +271,51 @@
           "items": {
             "type": "object",
             "additionalProperties": false,
-            "required": ["key", "kind", "label"],
+            "required": [
+              "key",
+              "kind",
+              "label"
+            ],
             "properties": {
-              "key": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9]{0,39}$" },
-              "kind": { "type": "string", "enum": ["color", "select", "toggle", "font"] },
-              "label": { "type": "string", "maxLength": 60 },
+              "key": {
+                "type": "string",
+                "pattern": "^[a-zA-Z][a-zA-Z0-9]{0,39}$"
+              },
+              "kind": {
+                "type": "string",
+                "enum": [
+                  "color",
+                  "select",
+                  "toggle",
+                  "font"
+                ]
+              },
+              "label": {
+                "type": "string",
+                "maxLength": 60
+              },
               "default": {},
-              "options": { "type": "array", "items": { "type": "string" } },
+              "options": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
               "group": {
                 "type": "string",
-                "enum": ["typography", "looks"],
-                "description": "Where the admin surfaces this knob: 'typography' → the Typography section beside the font slots; 'looks' → the Looks section with the one-click bundles (colour schemes and accent dials belong there, and ungrouped color knobs plus a knob keyed 'scheme' default there anyway); other ungrouped knobs render under Template options."
+                "enum": [
+                  "typography",
+                  "looks"
+                ],
+                "description": "Where the admin surfaces this knob: 'typography' \u2192 the Typography section beside the font slots; 'looks' \u2192 the Looks section with the one-click bundles (colour schemes and accent dials belong there, and ungrouped color knobs plus a knob keyed 'scheme' default there anyway); other ungrouped knobs render under Template options."
               },
               "weights": {
                 "type": "array",
-                "items": { "type": "integer", "minimum": 100, "maximum": 1000 },
+                "items": {
+                  "type": "integer",
+                  "minimum": 100,
+                  "maximum": 1000
+                },
                 "uniqueItems": true,
                 "description": "FONT knobs only: the weights this template's typographic system uses for the slot. The host requests these for the tenant's chosen family (clamped to the family's real weights). The tenant picks the FAMILY; weights, sizes and tracking stay template-owned."
               }

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

@@ -237,7 +237,7 @@
           "name": "images",
           "kind": "items",
           "required": false,
-          "description": "Hero photographs (0–6, uploaded through the platform pipeline). One = a main image; several = rotation material, a template with supports.heroImagery renders at least the first and MAY place the hero_carousel island (or a CSS scroll strip) for the rest. Like every field: absent means the template's designed no-photo state, never a placeholder.",
+          "description": "Hero photographs (0\u20136, uploaded through the platform pipeline). One = a main image; several = rotation material, a template with supports.heroImagery renders at least the first and MAY place the hero_carousel island (or a CSS scroll strip) for the rest. Like every field: absent means the template's designed no-photo state, never a placeholder.",
           "itemFields": [
             {
               "name": "imageUrl",
@@ -360,16 +360,16 @@
         "items": [
           {
             "imageUrl": "p60fixture:impact/parcel",
-            "title": "£10 · A family food parcel",
+            "title": "\u00a310 \u00b7 A family food parcel",
             "description": "Three days of meals, toiletries and a bag of fresh produce from the garden."
           },
           {
-            "icon": "🔥",
-            "title": "£25 · A warm week",
+            "icon": "\ud83d\udd25",
+            "title": "\u00a325 \u00b7 A warm week",
             "description": "Heating top-ups for a household choosing between eating and heating."
           },
           {
-            "title": "£50 · A month of youth club",
+            "title": "\u00a350 \u00b7 A month of youth club",
             "description": "Coaching, kit and hot food for a young person, four evenings a week."
           }
         ]
@@ -513,7 +513,7 @@
       "pages": [
         "home"
       ],
-      "description": "Big headline numbers, the at-a-glance impact band. Values are author-entered text (write them exactly as they should read).",
+      "description": "Big headline numbers, the at-a-glance impact band. Values are author-entered text (write them exactly as they should read), or, per item, a live figure the platform counts (`source`).",
       "fields": [
         {
           "name": "eyebrow",
@@ -544,6 +544,18 @@
               "kind": "text",
               "required": true,
               "description": "What it counts (e.g. meals served)."
+            },
+            {
+              "name": "source",
+              "kind": "select",
+              "required": false,
+              "options": [
+                "volunteers.active",
+                "volunteers.hoursThisYear",
+                "volunteers.opportunitiesOpen",
+                "volunteers.needed"
+              ],
+              "description": "A figure the platform counts rather than the author types (volunteers who helped in the last twelve months, hours logged this year, opportunities open now, volunteers still needed). When set, `value` is replaced at render with the live count, formatted for the site's locale; templates render `value` exactly as before."
             }
           ]
         }

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 };
+}