@taprootio/espalier 6.1.0 → 6.2.0

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+# 6.2.0
+
+Banners gain a soft height contract, so a banner capped to the first fold or filling the viewport never clips its copy.
+
+- **New: `--esp-image-banner-max-block-size`**, a soft cap. A banner is the smaller of its ratio height and the cap while its copy fits, exactly as with the same `max-block-size`, and grows past the cap when the copy (with its spacing) would not fit, giving the cap back once it does.
+- **New: `--esp-image-banner-block-size`**, a soft target that replaces the ratio as the banner height (viewport-fill banners), and that copy grows the banner past in the same way.
+- In the compact band (`compact-placement="below"`), the soft properties size only the image box and the band adds below it, so band copy is never clipped.
+- `@taprootio/espalier/image/banner-static.css` reads both properties, so server-rendered banners lay out the same before and after upgrade (where container style queries exist: Chrome and Safari 18+; elsewhere a soft height applies at upgrade).
+- **Fixed: a banner nested in another banner's overlay inherited the outer banner's ratio** when it had none of its own; it now keeps its image's own size. A real `max-block-size`, `block-size`, or `min-block-size` keeps its hard meaning, alongside a soft property too, and banners that set neither soft property are unchanged.
+
 # 6.1.0
 
 Banner overlays gain a copy-stack layout contract (supporting copy, one action, middle positions, a compact band, and a static first-paint layout), and pickers no longer pick the option a finger lands on when it starts scrolling.

package/css/image/banner-static.css

@@ -16,6 +16,10 @@
  *   --esp-image-static-compact-ratio  the `compact-ratio` value, if any
  *   --esp-image-object-position       the focal point, e.g. `65% 40%`
  *
+ * It also reads the element's own soft height properties, exactly as the
+ * upgraded element does: --esp-image-banner-max-block-size (a soft cap) and
+ * --esp-image-banner-block-size (a soft target).
+ *
  * Limits, all documented in the image banners guide: the compact switch uses
  * the default 40rem width (a custom `--esp-image-compact-width` cannot apply
  * before upgrade); no scrim or texture paints until upgrade; copy must be
@@ -41,8 +45,20 @@ esp-image[banner]:not(:defined) {
   container-type: inline-size;
 }
 
-/* The image spans every row at the banner ratio, so the banner is as tall as
-   the ratio or the copy, whichever is taller, and the image covers it all. */
+/* The image spans every row at the banner ratio (its own natural size when
+   there is none), so the banner is as tall as the ratio or the copy,
+   whichever is taller, and the image stretches to cover it all. An empty
+   spacer spans the rows too; it carries the soft height (below). */
+esp-image[banner]:not(:defined)::before {
+  content: "";
+  grid-row: 1 / -1;
+  grid-column: 1;
+  align-self: start;
+  justify-self: stretch;
+  aspect-ratio: var(--esp-image-static-ratio, auto);
+  block-size: var(--esp-image-banner-block-size, auto);
+  max-block-size: var(--esp-image-banner-max-block-size, none);
+}
 esp-image[banner]:not(:defined) > picture,
 esp-image[banner]:not(:defined) > img {
   display: block;
@@ -202,8 +218,29 @@ esp-image[banner][compact-placement="below"][banner-scheme="dark"]:not(:defined)
   esp-image[banner]:not(:defined) > :is(picture, img) {
     aspect-ratio: var(--esp-image-static-compact-ratio, var(--esp-image-static-ratio, auto));
   }
+  /* At compact widths a compact ratio alone is enough for a soft cap (see
+     the soft height rule below). */
+  @container (style(--esp-image-static-compact-ratio) and style(--esp-image-banner-max-block-size) and (not style(--esp-image-banner-max-block-size: none)) and (not style(--esp-image-banner-max-block-size: auto))) {
+    esp-image[banner]:not(:defined) > :is(picture, img) {
+      contain: size;
+      aspect-ratio: auto;
+    }
+  }
+  /* A pseudo-element can query its own originating element. */
+  esp-image[banner]:not(:defined)::before {
+    aspect-ratio: var(--esp-image-static-compact-ratio, var(--esp-image-static-ratio, auto));
+  }
+  /* The band: the image box takes the first row, sized like the spacer (the
+     soft height sizes only the image box), and the copy follows below. */
+  esp-image[banner][compact-placement="below"]:not(:defined)::before {
+    display: none;
+  }
   esp-image[banner][compact-placement="below"]:not(:defined) > :is(picture, img) {
     grid-row: 1;
+    contain: none;
+    aspect-ratio: var(--esp-image-static-compact-ratio, var(--esp-image-static-ratio, auto));
+    block-size: var(--esp-image-banner-block-size, auto);
+    max-block-size: var(--esp-image-banner-max-block-size, none);
   }
   esp-image[banner][compact-placement="below"]:not(:defined)
     > :is([slot="overlay"], [slot="overlay-supporting"], [slot="overlay-action"]) {
@@ -226,6 +263,21 @@ esp-image[banner][compact-placement="below"][banner-scheme="dark"]:not(:defined)
   }
 }
 
+/* Soft height, matching the element: a soft target, or a soft cap on a
+   banner with a static ratio, hands sizing to the spacer, so the image gives
+   up its own size (size containment, no ratio) and stretches over whatever
+   the spacer or the copy sets. none and auto count as unset. This needs
+   container style queries (Chrome, Safari 18+); elsewhere the soft height
+   applies at upgrade, and banners without it are unaffected. It follows the
+   compact rules so it wins over their image ratio; the band's image rule is
+   more specific and keeps its own sizing. */
+@container (style(--esp-image-banner-block-size) and (not style(--esp-image-banner-block-size: none)) and (not style(--esp-image-banner-block-size: auto))) or (style(--esp-image-static-ratio) and style(--esp-image-banner-max-block-size) and (not style(--esp-image-banner-max-block-size: none)) and (not style(--esp-image-banner-max-block-size: auto))) {
+  esp-image[banner]:not(:defined) > :is(picture, img) {
+    contain: size;
+    aspect-ratio: auto;
+  }
+}
+
 /* The image never moves under reduced motion, before upgrade as after. */
 @media (prefers-reduced-motion: reduce) {
   esp-image[banner]:not(:defined) > picture,