@taprootio/espalier 5.0.0 → 6.1.0

package/CHANGELOG.md

@@ -1,3 +1,24 @@
+# 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.
+
+- **Breaking: `esp-video` no longer takes a streaming adapter.** The `adapter` property, `EspalierVideo.defaultAdapter`, and the `VideoAdapter` type are gone, along with the `"adapter"` value of `VideoSourceMode` (the `mode` in event details) and of `VideoErrorReason`. The element plays `src` where the browser can play `type`, and `fallback-src` otherwise; for a source every browser plays, set `type="video/mp4"`. Nothing else about the element changes: `type` still defaults to HLS, which Safari, iOS, and current Chrome play natively.
+- **Fixed: a picker kept showing an item's old label after its text changed.** A picker copies its `esp-picker-item` children and removes them from the page, so a template that rewrote an item in place (Lit's `map` reusing elements by position, for example, when a placeholder entry is replaced by loaded data) changed nothing the picker saw, and `esp-pick-one` kept showing the placeholder. An item's `text`, `icon`, and `styles` changes now reach its picker: `esp-pick-one` re-renders the selected label, and `esp-pick-some` the selected chip. The selection follows the item's `value` and no `esp-value-changed` fires. `esp-pick-some` chips now also follow the new item when the items are replaced outright. An item element the picker no longer lists, whose `value` was rewritten, or whose items the host has since replaced from code, is ignored.
+- **Fixed: a typeahead picker with `fetchItems` replaced the server's results when its items changed.** Picking in `esp-pick-some`, or any change to `pickerItems`, re-ran the local filter over the canonical items and swapped the remote results shown in the menu for them. The menu now keeps the server's results, with their selected marks updated, and a chip keeps the label of the remote result the visitor picked until the item with that value changes or first arrives. Clearing `fetchItems` while a query is typed shows the local matches at once, and a request still in flight from the cleared source no longer brings its results back, or empties the menu if it fails.
+
 # 5.0.0
 
 Espalier 5 removes the compatibility paths kept for older consumers, adds a native video player, `esp-video`, and makes form errors perceivable to assistive technology: form-item errors now mark, describe, and announce the field, `esp-input` accepts `step="any"`, and choice groups take their name from the form item. The "Migrating To Espalier 5" guide lists each replacement and the form behavior to check.

package/css/image/banner-static.css

@@ -0,0 +1,237 @@
+/*
+ * 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%`
+ *
+ * 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, so the banner is as tall as
+   the ratio or the copy, whichever is taller, and the image covers it all. */
+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));
+  }
+  esp-image[banner][compact-placement="below"]:not(:defined) > :is(picture, img) {
+    grid-row: 1;
+  }
+  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)
+    );
+  }
+}
+
+/* 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;
+  }
+}