@port60/template-kit 0.3.0 → 0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@port60/template-kit",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "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/vendor/contract/v1/sections.json

@@ -223,6 +223,16 @@
      "required": false,
      "description": "Background photograph for the hero (uploaded through the platform pipeline). Superseded by `images` when that carries any entry — render imageUrl only when images is absent/empty. The template must TREAT the photo (scrim/tint from its own palette variables), never place it raw, and omit for its designed no-photo state."
     },
+    {
+     "name": "photoFraming",
+     "kind": "select",
+     "required": false,
+     "options": [
+      "fill",
+      "whole"
+     ],
+     "description": "How hero photographs meet the hero. 'fill' (default): the hero keeps its designed shape and photos crop to fill it (use each photo's focus to pick the surviving slice). 'whole': the hero adapts toward the photo's own shape (height-clamped) so the FULL scene stays visible — the vista treatment for wide landscape photographs; templates overlay or stack their copy accordingly."
+    },
     {
      "name": "images",
      "kind": "items",

package/starter/assets/theme.css

@@ -113,3 +113,42 @@ body { font-family: ' IBM Plex Sans Arabic', var(--p60s-siteFont, 'Inter'), ui-s
   cursor: pointer;
 }
 .lq-homehero--carousel .hero-dot--active { background: var(--accent); }
+
+/* ── Vista framing (photoFraming 'whole') — the hero adapts to the PHOTO's shape ───────────── */
+.lq-homehero--vista { padding-top: 0; }
+.lq-vista { position: relative; overflow: hidden; }
+.lq-vista-sizer { display: block; width: 100%; height: auto; max-height: 74vh; object-fit: cover; }
+.lq-vista-scrim,
+.lq-homehero--vista .hero-slide-scrim {
+  position: absolute;
+  inset: 0;
+  pointer-events: none;
+  background: linear-gradient(
+    180deg,
+    color-mix(in srgb, var(--bg) 45%, transparent) 0%,
+    color-mix(in srgb, var(--bg) 12%, transparent) 40%,
+    color-mix(in srgb, var(--bg-tint) 60%, transparent) 100%
+  );
+}
+.lq-homehero--vista .lq-homehero-inner { padding-top: 2.4rem; }
+.lq-homehero--vista .hero-carousel { position: absolute; inset: 0; z-index: 0; }
+
+/* Vista 1.5.1: copy ON the photograph (strengthened lower scrim); the widget follows in its
+   own strip; narrow screens flow the copy back underneath. */
+.lq-vista-copy { position: absolute; inset-inline: 0; bottom: 0; padding: 1.4rem 0 2rem; z-index: 1; }
+.lq-homehero--vista .lq-vista-scrim,
+.lq-homehero--vista .hero-slide-scrim {
+  background: linear-gradient(
+    180deg,
+    color-mix(in srgb, var(--bg) 38%, transparent) 0%,
+    color-mix(in srgb, var(--bg) 10%, transparent) 38%,
+    color-mix(in srgb, var(--bg-tint) 82%, transparent) 100%
+  );
+}
+.lq-vista-sizer { min-height: 280px; }
+.lq-vista-widget { padding: 2.2rem 0 0; display: flex; justify-content: center; }
+.lq-vista-widget aside { width: min(560px, 100%); }
+@media (max-width: 720px) {
+  .lq-vista-copy { position: static; padding: 1.8rem 0 0; }
+  .lq-vista-sizer { min-height: 160px; }
+}

package/starter/manifest.json

@@ -1,6 +1,6 @@
 {
  "name": "starter",
- "version": "1.4.0",
+ "version": "1.5.1",
  "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,5 @@
    }
   ]
  },
- "changelog": "Per-photo focus: choose which part of a hero photograph survives the fill-crop (centre/top/bottom/left/right) — panoramas and portraits stop cropping blind."
+ "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."
 }

package/starter/sections/homeHero.liquid

@@ -1,15 +1,18 @@
 {% comment %}
-  The home opener — and the REFERENCE IMPLEMENTATION of supports.heroImagery. Three rules worth
+  The home opener — and the REFERENCE IMPLEMENTATION of supports.heroImagery. Rules worth
   copying:
 
   1. EVERY field is optional. Copy derives from brand (| default) or omits; no photos means the
      designed gradient below — never a placeholder image.
-  2. Photos are NEVER placed raw. The .lq-homehero--photo treatment in theme.css lays a scrim
-     built from the palette variables (color-mix over var(--bg)/var(--primary)), so any uploaded
-     photograph is toned into the template. Tune the treatment, don't remove it.
-  3. Templates ship no JavaScript, so rotation is the PLATFORM's hero_carousel island: with two
-     or more photos, place it and style its documented classes (.hero-slide, .hero-slide-scrim,
-     .hero-dots) — the platform owns the motion, you own the look.
+  2. Photos are NEVER placed raw. The treatments in theme.css lay scrims built from the palette
+     variables (color-mix over var(--bg)/var(--bg-tint)), so any uploaded photograph is toned
+     into the template. Tune the treatment, don't remove it.
+  3. Rotation is the PLATFORM's hero_carousel island (templates ship no JavaScript): with two or
+     more photos, place it and style its documented classes.
+  4. photoFraming is the charity's call, honour BOTH: 'fill' (default) covers your designed hero
+     shape (per-photo focus picks the surviving slice); 'whole' is the VISTA — the hero adapts
+     toward the photo's own shape (height-clamped) so a wide landscape stays entirely visible,
+     with your copy stacked after the band.
 {% endcomment %}
 {% assign heroCount = section.images | size %}
 {% if heroCount == 1 %}
@@ -26,6 +29,37 @@
     {% when 'right' %}{% assign heroFocus = 'right center' %}
   {% endcase %}
 {% endif %}
+{% assign heroFraming = section.photoFraming | default: 'fill' %}
+{% if heroCount > 0 and heroFraming == 'whole' %}
+<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">
+    {% if heroCount > 1 %}{% island 'hero_carousel' %}{% else %}<div class="lq-vista-scrim" aria-hidden="true"></div>{% endif %}
+    <div class="lq-vista-copy">
+      <div class="container">
+        <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">
+          {% 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">
+    <aside id="donate">
+      {% island 'donation_widget' %}
+    </aside>
+  </div>
+  {% endunless %}
+</section>
+{% 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 %}
   <div class="container lq-homehero-inner">
@@ -49,3 +83,4 @@
     {% endunless %}
   </div>
 </section>
+{% endif %}