@port60/template-kit 0.4.1 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@port60/template-kit",
-  "version": "0.4.1",
+  "version": "0.5.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/lib/agentsMd.mjs

@@ -70,6 +70,9 @@ 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.
+- \`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.
 
 ## Which contract this is
 

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

@@ -0,0 +1,23 @@
+{
+ "description": "Platform imagery envelopes — ADVICE, never enforcement. Entity images (events, courses, articles) render on SEVERAL surfaces at once (cards, carousel slides, detail banners), including platform-owned components, so their guidance is platform-level: the envelope every surface can live with. Template-composed slots (the home hero) are different — their ideal is the TEMPLATE's own design call, declared per-template in manifest.imagery and surfaced beside the upload. Editors measure the actual upload against the relevant guidance and advise; the charity always decides.",
+ "entityImages": {
+  "eventPromo": {
+   "idealAspect": "3:2",
+   "aspectRange": ["4:3", "16:9"],
+   "minWidth": 1600,
+   "note": "One photo, several surfaces: the events card, the home carousel slide, and the event page banner — each crops differently, so keep the subject centred and avoid text baked into the image."
+  },
+  "courseImage": {
+   "idealAspect": "3:2",
+   "aspectRange": ["4:3", "16:9"],
+   "minWidth": 1600,
+   "note": "Renders as the course card and the course page opener — subject centred, no baked-in text."
+  },
+  "articleCover": {
+   "idealAspect": "16:9",
+   "aspectRange": ["3:2", "2:1"],
+   "minWidth": 1600,
+   "note": "The article card thumbnail and the article page cover — wide editorial shots sit best."
+  }
+ }
+}

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

@@ -78,6 +78,35 @@
         }
       }
     },
+    "imagery": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "The template's OWN image advice, surfaced beside uploads in the charity's editor — a design statement (what shape suits THIS composition), advisory only, never enforced. Entity images (events, courses, articles) are platform-scoped instead: see the contract's imagery.json envelopes.",
+      "properties": {
+        "hero": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["idealAspect", "minWidth"],
+          "properties": {
+            "idealAspect": {
+              "type": "string",
+              "pattern": "^\\d+:\\d+$",
+              "description": "The aspect this hero composes best with, e.g. \"16:9\"."
+            },
+            "minWidth": {
+              "type": "integer",
+              "minimum": 800,
+              "description": "Below this pixel width the photo may look soft full-bleed."
+            },
+            "note": {
+              "type": "string",
+              "maxLength": 240,
+              "description": "One human line of advice, e.g. how panoramas or portraits behave in this hero."
+            }
+          }
+        }
+      }
+    },
     "fonts": {
       "type": "array",
       "items": {

package/starter/assets/theme.css

@@ -152,3 +152,11 @@ body { font-family: ' IBM Plex Sans Arabic', var(--p60s-siteFont, 'Inter'), ui-s
   .lq-vista-copy { position: static; padding: 1.8rem 0 0; }
   .lq-vista-sizer { min-height: 160px; }
 }
+
+/* Vista + form (1.5.2): the widget rides the seam — grid pulled up over the band (under the
+   280px floor), gradient filling where the image ends; narrow screens stack back underneath. */
+.lq-homehero--vista-form { padding-bottom: 2.6rem; }
+.lq-vista-overlap { position: relative; z-index: 1; margin-top: -240px; align-items: start; }
+@media (max-width: 899px) {
+  .lq-vista-overlap { margin-top: 0; padding-top: 1.6rem; }
+}

package/starter/manifest.json

@@ -1,6 +1,6 @@
 {
  "name": "starter",
- "version": "1.5.1",
+ "version": "1.5.3",
  "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.",
@@ -40,5 +40,12 @@
    }
   ]
  },
- "changelog": "Vista polish: your headline and buttons now sit ON the photograph (the treatment keeps them readable) instead of stacking below it — the hero no longer doubles in height."
+ "changelog": "Declares image advice: the ideal photo shape for this hero, shown beside the upload in your editor.",
+ "imagery": {
+  "hero": {
+   "idealAspect": "16:9",
+   "minWidth": 1600,
+   "note": "Landscape around 16:9 fills the hero cleanly; panoramas suit the whole-photo framing."
+  }
+ }
 }

package/starter/sections/homeHero.liquid

@@ -31,6 +31,7 @@
 {% endif %}
 {% assign heroFraming = section.photoFraming | default: 'fill' %}
 {% if heroCount > 0 and heroFraming == 'whole' %}
+{% if 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">
@@ -41,24 +42,37 @@
         <h1>{{ section.title | default: brand.tagline | default: 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>
-          {% else %}
-          <a class="button button-primary" href="#donate">{{ section.primaryLabel | default: 'Donate now' }}</a>
-          {% endif %}
           <a class="button" href="{{ section.secondaryHref | default: '/about' }}">{{ section.secondaryLabel | default: 'Our story' }}</a>
         </div>
       </div>
     </div>
   </div>
-  {% unless section.givingStyle == 'button' %}
-  <div class="container lq-vista-widget">
+</section>
+{% else %}
+{% comment %} Form mode: the grid pulls up over the band — copy on the photo, the widget riding
+    the seam onto the gradient below (never a stacked strip). {% endcomment %}
+<section class="lq-homehero lq-homehero--vista lq-homehero--vista-form{% 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">
+    {% if heroCount > 1 %}{% island 'hero_carousel' %}{% else %}<div class="lq-vista-scrim" aria-hidden="true"></div>{% endif %}
+  </div>
+  <div class="container lq-homehero-inner lq-vista-overlap">
+    <div>
+      <p class="lq-kicker">{{ section.eyebrow | default: brand.name }}</p>
+      <h1>{{ section.title | default: brand.tagline | default: 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>
+        <a class="button" href="{{ section.secondaryHref | default: '/about' }}">{{ section.secondaryLabel | default: 'Our story' }}</a>
+      </div>
+    </div>
     <aside id="donate">
       {% island 'donation_widget' %}
     </aside>
   </div>
-  {% endunless %}
 </section>
+{% endif %}
 {% else %}
 <section class="lq-homehero{% if heroPhoto %} lq-homehero--photo{% endif %}{% if heroCount > 1 %} lq-homehero--carousel{% endif %}"{% if heroPhoto %} style="background-image: url('{{ heroPhoto }}'); background-position: {{ heroFocus }}"{% endif %}>
   {% if heroCount > 1 %}{% island 'hero_carousel' %}{% endif %}