@taprootio/espalier 6.0.0 → 6.2.0

package/CHANGELOG.md

@@ -1,3 +1,26 @@
+# 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.
+
+- **New: middle content positions.** `esp-image`'s `content-position` takes `middle-start` and `middle-end`, centering the copy against the inline start or end edge and mirroring in right-to-left text. An `auto` scrim follows the copy to that edge.
+- **New: a banner copy stack.** Beside `slot="overlay"` (the headline), banners take `slot="overlay-supporting"` for one supporting sentence and `slot="overlay-action"` for one native link or button. Together they lay out as one stack: grouped spacing (`--esp-image-overlay-gap`), the supporting sentence on the lead type role, a line length bounded by `--esp-image-overlay-measure` (`36rem` by default), and an action with a comfortable target and a two-tone focus ring that reads over any photograph. The scrim now covers every piece of overlay copy, not just the headline. A headline on its own lays out exactly as before.
+- **New: `compact-placement="below"`.** Below the compact width the copy moves into a band under the image, on the banner scheme's own surface and ink, for crops that lose their quiet region at narrow widths. The default, `overlay`, keeps today's behavior.
+- **New: `@taprootio/espalier/image/banner-static.css`.** A stylesheet that lays server-rendered banners out before `esp-image` upgrades, from the same attributes plus `--esp-image-static-ratio` and `--esp-image-static-compact-ratio`, so nothing shifts at hydration. The Image banners guide lists its inputs and limits.
+- **Fixed: banner copy could be clipped.** Copy taller than the ratio's frame (text enlarged to 200%, long localized labels, a narrow column) was cut off; the banner now grows to fit it, the image covers the grown frame, and words too long for a line wrap. A banner whose copy fits keeps exactly its current geometry, and an explicit, capped, or stretched block size still wins.
+- **Banner copy never moves with the image.** A transform or animation on a banner's projected image or `::part(image)` stays inside the image box, and under `prefers-reduced-motion` those animations and transitions stop.
+- **Fixed: swiping a picker's option list picked the first option touched.** Pickers picked on the press, before the browser could tell a tap from a scroll, so on a phone every swipe chose an option and closed the menu; `esp-pick-one` also picked a hidden option behind its input when the input was tapped after scrolling. Options are now picked by the tap that ends on them, a press keeps focus (and a typeahead query) in the input, and a tap on the input only focuses it. This applies to `esp-pick-one`, `esp-pick-some`, and `esp-font-picker`, with or without typeahead.
+- **Fixed: typing a typeahead filter after scrolling a long picker list could throw** while the list shrank.
+
 # 6.0.0
 
 Espalier 6 removes `esp-video`'s unused streaming adapter, and pickers now show an item's new label when its text changes after it was selected.

package/css/image/banner-static.css

@@ -0,0 +1,289 @@
+/*
+ * Espalier esp-image banner: static layout before the component upgrades.
+ *
+ * Server-rendered `<esp-image banner>` markup paints with page styles alone
+ * until Espalier's module defines the element. This sheet lays the same
+ * markup out from its attributes in that window, matching the upgraded
+ * banner's geometry so nothing shifts at hydration: the frame ratio, focal
+ * cropping, every `content-position`, the copy stack and its measure, growth
+ * for long or enlarged copy, and `compact-placement="below"`.
+ *
+ * Every rule is scoped to `esp-image[banner]:not(:defined)`, so it stops
+ * applying the moment the element upgrades.
+ *
+ * Inputs the server sets inline (CSS cannot read a ratio from an attribute):
+ *   --esp-image-static-ratio          the `ratio` value, e.g. `3 / 1`
+ *   --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
+ * emitted in stack order (headline, supporting, action); and a custom
+ * `--esp-image-overlay-padding` must be a single length for the compact band.
+ */
+
+esp-image[banner]:not(:defined) {
+  --_esp-image-static-pad: var(--esp-image-overlay-padding, var(--esp-size-padding-page, 1rem));
+  --_esp-image-static-gap: var(--esp-image-overlay-gap, var(--esp-size-small, 0.75rem));
+  --_esp-image-static-before: 1fr;
+  --_esp-image-static-after: 0fr;
+  display: grid;
+  grid-template-columns: minmax(0, 1fr);
+  /* media | space before | headline | supporting | action | space after */
+  grid-template-rows:
+    auto minmax(0, var(--_esp-image-static-before)) auto auto auto
+    minmax(0, var(--_esp-image-static-after));
+  justify-items: start;
+  text-align: start;
+  overflow: clip;
+  overflow-wrap: anywhere;
+  container-type: inline-size;
+}
+
+/* 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;
+  grid-row: 1 / -1;
+  grid-column: 1;
+  align-self: stretch;
+  justify-self: stretch;
+  inline-size: 100%;
+  block-size: auto;
+  aspect-ratio: var(--esp-image-static-ratio, auto);
+  object-fit: cover;
+  object-position: var(--esp-image-object-position, center);
+}
+esp-image[banner]:not(:defined) > picture > img {
+  display: block;
+  inline-size: 100%;
+  block-size: 100%;
+  object-fit: cover;
+  object-position: var(--esp-image-object-position, center);
+}
+esp-image[banner]:not(:defined) > esp-image-option {
+  display: none;
+}
+
+/* Vertical placement: which side of the copy takes the free space. */
+esp-image[banner]:not(:defined):is(
+    [content-position="top-start"],
+    [content-position="top"],
+    [content-position="top-end"]
+  ) {
+  --_esp-image-static-before: 0fr;
+  --_esp-image-static-after: 1fr;
+}
+esp-image[banner]:not(:defined):is(
+    [content-position="middle-start"],
+    [content-position="center"],
+    [content-position="middle-end"]
+  ) {
+  --_esp-image-static-before: 1fr;
+  --_esp-image-static-after: 1fr;
+}
+/* Inline placement, logical so right-to-left mirrors. */
+esp-image[banner]:not(:defined):is(
+    [content-position="top"],
+    [content-position="center"],
+    [content-position="bottom"]
+  ) {
+  justify-items: center;
+  text-align: center;
+}
+esp-image[banner]:not(:defined):is(
+    [content-position="top-end"],
+    [content-position="middle-end"],
+    [content-position="bottom-end"]
+  ) {
+  justify-items: end;
+  text-align: end;
+}
+
+/* The copy. The upgraded overlay pads the copy as a block; here each piece of
+   copy carries that padding itself, as a margin, so the image stays
+   full-bleed. A headline on its own keeps its own margins, as it does once
+   upgraded, by taking the padding as padding instead. */
+esp-image[banner]:not(:defined) > :is([slot="overlay"], [slot="overlay-supporting"], [slot="overlay-action"]) {
+  grid-column: 1;
+  min-inline-size: 0;
+}
+esp-image[banner]:not(:defined) > [slot="overlay"] {
+  grid-row: 3;
+  max-inline-size: var(--esp-image-overlay-measure, none);
+  padding: var(--_esp-image-static-pad);
+}
+/* A lone headline carries the overlay padding here; content-box keeps a
+   measure bounding its text, as after upgrade, where that padding belongs to
+   the overlay rather than the headline. */
+esp-image[banner]:not(:defined):not(:has(> [slot="overlay-supporting"], > [slot="overlay-action"]))
+  > [slot="overlay"] {
+  box-sizing: content-box;
+}
+esp-image[banner]:not(:defined) > [slot="overlay-supporting"] {
+  grid-row: 4;
+}
+esp-image[banner]:not(:defined) > [slot="overlay-action"] {
+  grid-row: 5;
+}
+
+/* A copy stack: supporting copy or an action is present. */
+esp-image[banner]:not(:defined):has(> [slot="overlay-supporting"], > [slot="overlay-action"])
+  > :is([slot="overlay"], [slot="overlay-supporting"], [slot="overlay-action"]) {
+  max-inline-size: var(--esp-image-overlay-measure, 36rem);
+  margin: var(--_esp-image-static-pad) !important;
+}
+esp-image[banner]:not(:defined):has(> [slot="overlay-supporting"], > [slot="overlay-action"])
+  > [slot="overlay"] {
+  padding: 0;
+}
+esp-image[banner]:not(:defined):has(> [slot="overlay-supporting"], > [slot="overlay-action"])
+  > [slot="overlay"]:has(~ [slot="overlay-supporting"], ~ [slot="overlay-action"]) {
+  margin-block-end: 0 !important;
+}
+esp-image[banner]:not(:defined) > [slot="overlay"] ~ [slot="overlay-supporting"] {
+  margin-block-start: var(--_esp-image-static-gap) !important;
+}
+esp-image[banner]:not(:defined) > [slot="overlay-supporting"]:has(~ [slot="overlay-action"]) {
+  margin-block-end: 0 !important;
+}
+esp-image[banner]:not(:defined)
+  > :is([slot="overlay"], [slot="overlay-supporting"])
+  ~ [slot="overlay-action"] {
+  margin-block-start: calc(2 * var(--_esp-image-static-gap)) !important;
+}
+
+/* Defaults the upgraded overlay gives its supporting copy and action. They
+   carry no specificity, so page styles win here exactly as they do after
+   upgrade. */
+:where(esp-image[banner]:not(:defined)) > :where([slot="overlay-supporting"]) {
+  font-family: var(--esp-font-body, inherit);
+  font-weight: var(--esp-type-lead-font-weight, var(--esp-font-weight-body, 400));
+  font-size: var(--esp-type-lead-font-size, 1.25rem);
+  line-height: 1.4;
+}
+:where(esp-image[banner]:not(:defined)) > :where(a[slot="overlay-action"], button[slot="overlay-action"]) {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  box-sizing: border-box;
+  min-block-size: 2.75rem;
+  padding: 0.5em 1.25em;
+  border: 2px solid currentColor;
+  border-radius: var(--esp-size-border-radius, 0.375rem);
+  background: transparent;
+  font-family: var(--esp-font-body, inherit);
+  font-size: var(--esp-type-normal, 1rem);
+  font-weight: 600;
+  line-height: 1.2;
+  text-align: center;
+}
+
+/* Compact band: below the default compact width the image keeps the compact
+   ratio in its own row and the copy follows on the banner scheme's surface. */
+esp-image[banner][compact-placement="below"]:not(:defined) {
+  background-color: var(--esp-image-scrim-color, var(--esp-color-background, oklch(0.98 0 0)));
+}
+esp-image[banner][compact-placement="below"][banner-scheme="light"]:not(:defined) {
+  background-color: var(
+    --esp-image-scrim-color,
+    oklch(from var(--esp-color-background, oklch(0.98 0 0)) 0.97 c h)
+  );
+}
+esp-image[banner][compact-placement="below"][banner-scheme="dark"]:not(:defined) {
+  background-color: var(
+    --esp-image-scrim-color,
+    oklch(from var(--esp-color-background, oklch(0.98 0 0)) 0.13 c h)
+  );
+}
+@container (width < 40rem) {
+  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"]) {
+    color: var(--esp-image-overlay-color, var(--esp-color-headings, oklch(0.2 0 0)));
+    text-shadow: none;
+  }
+  esp-image[banner][compact-placement="below"][banner-scheme="light"]:not(:defined)
+    > :is([slot="overlay"], [slot="overlay-supporting"], [slot="overlay-action"]) {
+    color: var(
+      --esp-image-overlay-color,
+      oklch(from var(--esp-color-headings, oklch(0.2 0 0)) 0.2 c h)
+    );
+  }
+  esp-image[banner][compact-placement="below"][banner-scheme="dark"]:not(:defined)
+    > :is([slot="overlay"], [slot="overlay-supporting"], [slot="overlay-action"]) {
+    color: var(
+      --esp-image-overlay-color,
+      oklch(from var(--esp-color-headings, oklch(0.2 0 0)) 0.97 c h)
+    );
+  }
+}
+
+/* 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,
+  esp-image[banner]:not(:defined) > picture > img,
+  esp-image[banner]:not(:defined) > img {
+    animation: none !important;
+    transition: none !important;
+  }
+}