@port60/template-kit 0.16.0 → 0.17.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",
+      "label": "Primary action",
+      "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.",
+      "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 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."
         }
       }
     },
@@ -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/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. */