@kubex/zinc 1.1.119 → 1.1.120

package/dist/zn.d.ts

@@ -7322,30 +7322,49 @@ declare module "components/form-group/form-group.component" {
         forceCols: boolean;
         layout: string;
         pad: boolean;
-        /** The scroll containers we have clipped, against the inline overflow each carried before. */
-        private readonly clipped;
+        /** The scroller the label is moved against by hand; null while native sticky is enough. */
+        private tracked;
+        /** Set while the compositor is running the movement off a scroll timeline instead. */
+        private animation;
+        private stickyTop;
         private frame;
+        private rebind;
+        private offset;
         private resizeObserver;
         connectedCallback(): void;
         disconnectedCallback(): void;
         protected firstUpdated(changedProperties: PropertyValues): void;
         private get labelColumn();
-        /** Coalesces resize work into one frame, and out of the ResizeObserver callback. */
+        /** Coalesces scroll and resize work into one frame, and out of the ResizeObserver callback. */
         private schedule;
-        private readonly onViewportResize;
         /**
-         * Native sticky anchors to the nearest scroll container, even one that cannot scroll — a `zn-panel` body sized to
-         * its content, say — where it then holds the label still for the whole scroll. `overflow: clip` clips without
-         * making a scroll container, so clipping those takes them out of sticky's search and the label follows the box the
-         * user actually scrolls, moved by the compositor rather than by hand.
-         */
-        private freeSticky;
-        private clip;
-        private release;
+         * Native sticky only follows the nearest scroll container. Where that container isn't the one
+         * the user actually scrolls — a `zn-panel` body sized to its content inside a scrolling
+         * slideout, say — the label never moves, so it is moved against the real scroller instead.
+         */
+        private bind;
+        /**
+         * The label's whole journey, as the scroll positions it turns at: still until the fieldset's top reaches the sticky
+         * line, then a pixel for every pixel of scroll until it has crossed the fieldset. `fill: both` holds it at either
+         * end, which is the clamp the scroll handler applies by hand.
+         */
+        private scrollLinkedTravel;
+        /** Drops everything this component has put on the label or on the scroller. */
+        private detach;
+        /** The document scrolls through the window, every other scroller reports its own events. */
+        private scrollTarget;
+        /** Where the scroller's own top edge sits, which for the document is the top of the viewport. */
+        private visibleTop;
+        private get fieldset();
+        private readonly onScroll;
+        private readonly onScrollEnd;
+        private readonly onViewportResize;
+        private positionLabel;
         /** The box native sticky would anchor to, whether or not it can be scrolled. */
-        private isStickyAnchor;
+        private nearestScrollContainer;
+        /** The nearest ancestor the user can actually scroll, falling back to the document. */
+        private scrollingAncestor;
         private isScrollContainer;
-        private overflows;
         /** Walks the flattened tree, so slots and shadow boundaries are crossed the way layout does. */
         private ancestors;
         render(): import("lit-html").TemplateResult<1>;

package/dist/zn.min.js

@@ -3385,7 +3385,7 @@ ${Na(this.code(i,t))}
         </zn-button>`:""}
       <zn-button part="submit-button" color="primary" icon="${this.submitIcon}" @click="${this.handleSubmit}">
         ${this.submitText}
-      </zn-button>`}};gr.styles=z(V_),gr.dependencies={"zn-button":De},c([p({attribute:"submit-text"})],gr.prototype,"submitText",2),c([p({attribute:"submit-icon"})],gr.prototype,"submitIcon",2),c([p({attribute:"with-cancel",type:Boolean})],gr.prototype,"withCancel",2),c([p({attribute:"cancel-text"})],gr.prototype,"cancelText",2),c([p({attribute:"cancel-icon"})],gr.prototype,"cancelIcon",2),c([p({attribute:"with-reset",type:Boolean})],gr.prototype,"withReset",2),c([p({attribute:"reset-text"})],gr.prototype,"resetText",2),c([p({attribute:"reset-icon"})],gr.prototype,"resetIcon",2),c([p()],gr.prototype,"form",2);var QM=gr;gr.define("zn-form-actions");var U_=_`@keyframes rotate-gradient{from{--rotate:0deg}to{--rotate:360deg}}:host{text-rendering:optimizeLegibility;-webkit-font-smoothing:antialiased;-moz-osx-font-smoothing:grayscale;text-transform:none}*,*::before,*::after{box-sizing:border-box;border-width:0;border-style:solid;border-color:rgb(var(--zn-border-color))}[hidden]{display:none !important}.width-container,.form-container,.wide-form-container{height:100%;width:100%;margin:var(--zn-default-margin,0 auto)}.width-container{max-width:var(--zn-container)}.form-container{max-width:var(--zn-container-ph)}.wide-form-container{max-width:var(--zn-container-lg)}:host{display:block;line-height:var(--zn-line-height-dense);max-width:var(--zn-container-lg);--zn-col-gap:calc(var(--zn-spacing-medium,20px) * 3);--zn-form-group-sticky-top:var(--zn-spacing-medium,20px)}.form-control{position:relative;border:none;padding:0;margin:0}.form-control__label{padding:0}.form-control--has-label .form-control__label{font-weight:var(--zn-font-weight-bold);font-size:var(--zn-font-size-large)}.form-control__container{--zn-col-basis:200px}@container (min-width:670px){.form-control__text{position:sticky;top:var(--zn-form-group-sticky-top);align-self:flex-start}}.form-control__chip{margin-top:var(--zn-spacing-x-small)}.visually-hidden{position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0,0,0,0);white-space:nowrap;border:0}.form-control-input{display:grid;grid-template-columns:minmax(0,1fr);gap:var(--zn-spacing-medium) var(--zn-spacing-small)}@media (min-width:768px){.form-control-input{grid-template-columns:repeat(6,minmax(0,1fr))}}.form-control-input>::slotted(*){grid-column:span 6/span 6}@media (min-width:768px){.form-control-input>::slotted([span="1"]){grid-column:span 1/span 1}}@media (min-width:768px){.form-control-input>::slotted([span="2"]){grid-column:span 2/span 2}}@media (min-width:768px){.form-control-input>::slotted([span="3"]){grid-column:span 3/span 3}}@media (min-width:768px){.form-control-input>::slotted([span="4"]){grid-column:span 4/span 4}}@media (min-width:768px){.form-control-input>::slotted([span="5"]){grid-column:span 5/span 5}}zn-cols::part(base){gap:70px}.form-control--pad .form-control__text{padding-top:var(--zn-base-gap);padding-left:var(--zn-base-gap)}`;var ki=class extends C{constructor(){super(...arguments);this.hasSlotController=new Y(this,"help-text","label","chip");this.label="";this.labelTooltip="";this.helpText="";this.forceCols=!1;this.layout="1,2";this.pad=!1;this.clipped=new Map;this.frame=0;this.resizeObserver=null;this.onViewportResize=()=>this.schedule()}connectedCallback(){super.connectedCallback(),this.resizeObserver??(this.resizeObserver=new ResizeObserver(()=>this.schedule())),this.resizeObserver.observe(this),window.addEventListener("resize",this.onViewportResize)}disconnectedCallback(){super.disconnectedCallback(),this.resizeObserver?.disconnect(),window.removeEventListener("resize",this.onViewportResize),this.release([...this.clipped.keys()]),cancelAnimationFrame(this.frame),this.frame=0}firstUpdated(t){super.firstUpdated(t),this.schedule()}get labelColumn(){return this.shadowRoot?.querySelector(".form-control__text")??null}schedule(){this.frame||(this.frame=requestAnimationFrame(()=>{this.frame=0,this.freeSticky()}))}freeSticky(){let t=this.labelColumn;if(!t)return;let r=[];for(let n of this.ancestors(t))if(!(!this.clipped.has(n)&&!this.isStickyAnchor(n))){if(this.overflows(n))break;r.push(n)}this.release([...this.clipped.keys()].filter(n=>!r.includes(n))),r.filter(n=>!this.clipped.has(n)).forEach(n=>this.clip(n))}clip(t){let r=n=>n==="clip"?"":n;this.clipped.set(t,{x:r(t.style.overflowX),y:r(t.style.overflowY)}),t.style.overflowX="clip",t.style.overflowY="clip",this.resizeObserver?.observe(t)}release(t){t.forEach(r=>{let n=this.clipped.get(r);r.style.overflowX=n?.x??"",r.style.overflowY=n?.y??"",this.resizeObserver?.unobserve(r),this.clipped.delete(r)})}isStickyAnchor(t){let r=getComputedStyle(t);return this.isScrollContainer(r.overflowY)||this.isScrollContainer(r.overflowX)}isScrollContainer(t){return t==="auto"||t==="scroll"||t==="hidden"||t==="overlay"}overflows(t){return t.scrollHeight>t.clientHeight+1||t.scrollWidth>t.clientWidth+1}ancestors(t){let r=[],n=t;for(;n;){let a=n instanceof Element&&n.assignedSlot?n.assignedSlot:n.parentNode instanceof ShadowRoot?n.parentNode.host:n.parentNode;a instanceof HTMLElement&&r.push(a),n=a}return r}render(){let t=this.hasSlotController.test("label"),r=this.hasSlotController.test("label-tooltip"),n=this.hasSlotController.test("help-text"),a=this.label?!0:t,s=this.labelTooltip?!0:r,l=this.helpText?!0:n,d=this.hasSlotController.test("chip");return u`
+      </zn-button>`}};gr.styles=z(V_),gr.dependencies={"zn-button":De},c([p({attribute:"submit-text"})],gr.prototype,"submitText",2),c([p({attribute:"submit-icon"})],gr.prototype,"submitIcon",2),c([p({attribute:"with-cancel",type:Boolean})],gr.prototype,"withCancel",2),c([p({attribute:"cancel-text"})],gr.prototype,"cancelText",2),c([p({attribute:"cancel-icon"})],gr.prototype,"cancelIcon",2),c([p({attribute:"with-reset",type:Boolean})],gr.prototype,"withReset",2),c([p({attribute:"reset-text"})],gr.prototype,"resetText",2),c([p({attribute:"reset-icon"})],gr.prototype,"resetIcon",2),c([p()],gr.prototype,"form",2);var QM=gr;gr.define("zn-form-actions");var U_=_`@keyframes rotate-gradient{from{--rotate:0deg}to{--rotate:360deg}}:host{text-rendering:optimizeLegibility;-webkit-font-smoothing:antialiased;-moz-osx-font-smoothing:grayscale;text-transform:none}*,*::before,*::after{box-sizing:border-box;border-width:0;border-style:solid;border-color:rgb(var(--zn-border-color))}[hidden]{display:none !important}.width-container,.form-container,.wide-form-container{height:100%;width:100%;margin:var(--zn-default-margin,0 auto)}.width-container{max-width:var(--zn-container)}.form-container{max-width:var(--zn-container-ph)}.wide-form-container{max-width:var(--zn-container-lg)}:host{display:block;line-height:var(--zn-line-height-dense);max-width:var(--zn-container-lg);--zn-col-gap:calc(var(--zn-spacing-medium,20px) * 3);--zn-form-group-sticky-top:var(--zn-spacing-medium,20px)}.form-control{position:relative;border:none;padding:0;margin:0}.form-control__label{padding:0}.form-control--has-label .form-control__label{font-weight:var(--zn-font-weight-bold);font-size:var(--zn-font-size-large)}.form-control__container{--zn-col-basis:200px}@container (min-width:670px){.form-control__text{position:sticky;top:var(--zn-form-group-sticky-top);align-self:flex-start}}.form-control__chip{margin-top:var(--zn-spacing-x-small)}.visually-hidden{position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0,0,0,0);white-space:nowrap;border:0}.form-control-input{display:grid;grid-template-columns:minmax(0,1fr);gap:var(--zn-spacing-medium) var(--zn-spacing-small)}@media (min-width:768px){.form-control-input{grid-template-columns:repeat(6,minmax(0,1fr))}}.form-control-input>::slotted(*){grid-column:span 6/span 6}@media (min-width:768px){.form-control-input>::slotted([span="1"]){grid-column:span 1/span 1}}@media (min-width:768px){.form-control-input>::slotted([span="2"]){grid-column:span 2/span 2}}@media (min-width:768px){.form-control-input>::slotted([span="3"]){grid-column:span 3/span 3}}@media (min-width:768px){.form-control-input>::slotted([span="4"]){grid-column:span 4/span 4}}@media (min-width:768px){.form-control-input>::slotted([span="5"]){grid-column:span 5/span 5}}zn-cols::part(base){gap:70px}.form-control--pad .form-control__text{padding-top:var(--zn-base-gap);padding-left:var(--zn-base-gap)}`;var ki=class extends C{constructor(){super(...arguments);this.hasSlotController=new Y(this,"help-text","label","chip");this.label="";this.labelTooltip="";this.helpText="";this.forceCols=!1;this.layout="1,2";this.pad=!1;this.tracked=null;this.animation=null;this.stickyTop=0;this.frame=0;this.rebind=!1;this.offset=0;this.resizeObserver=null;this.onScroll=()=>this.schedule();this.onScrollEnd=()=>this.schedule(!0);this.onViewportResize=()=>this.schedule(!0)}connectedCallback(){super.connectedCallback(),this.resizeObserver??(this.resizeObserver=new ResizeObserver(()=>this.schedule(!0))),this.resizeObserver.observe(this),window.addEventListener("resize",this.onViewportResize)}disconnectedCallback(){super.disconnectedCallback(),this.resizeObserver?.disconnect(),window.removeEventListener("resize",this.onViewportResize),this.detach(),cancelAnimationFrame(this.frame),this.frame=0}firstUpdated(t){super.firstUpdated(t),this.schedule(!0)}get labelColumn(){return this.shadowRoot?.querySelector(".form-control__text")??null}schedule(t=!1){this.rebind||(this.rebind=t),!this.frame&&(this.frame=requestAnimationFrame(()=>{this.frame=0,this.rebind&&(this.rebind=!1,this.bind()),this.positionLabel()}))}bind(){let t=this.labelColumn;if(!t)return;this.detach(),t.style.top="",this.stickyTop=parseFloat(getComputedStyle(t).top)||0;let r=this.nearestScrollContainer(t);if(!r)return;let n=this.scrollingAncestor(t);if(n!==r&&(t.style.top="0px",!!n)){if(this.tracked=n,this.animation=this.scrollLinkedTravel(n),this.animation){this.animation.play(),this.scrollTarget(n)?.addEventListener("scrollend",this.onScrollEnd,{passive:!0});return}this.scrollTarget(n)?.addEventListener("scroll",this.onScroll,{passive:!0})}}scrollLinkedTravel(t){let r=this.labelColumn,n=this.fieldset;if(!r||!n||typeof ScrollTimeline>"u"||getComputedStyle(r).position!=="sticky")return null;let a=Math.max(0,n.clientHeight-r.offsetHeight),s=t.scrollHeight-t.clientHeight;if(a<1||s<1)return null;let l=t.scrollTop+r.getBoundingClientRect().top-this.visibleTop(t)-this.stickyTop,d=f=>Math.min(Math.max(f-l,0),a),m=[0,...[l,l+a].filter(f=>f>0&&f<s),s].map(f=>({offset:Math.min(Math.max(f/s,0),1),transform:`translateY(${d(f)}px)`}));return new Animation(new KeyframeEffect(r,m,{fill:"both"}),new ScrollTimeline({source:t,axis:"block"}))}detach(){let t=this.scrollTarget(this.tracked);t?.removeEventListener("scroll",this.onScroll),t?.removeEventListener("scrollend",this.onScrollEnd),this.tracked=null,this.animation?.cancel(),this.animation=null;let r=this.labelColumn;r&&(this.offset=0,r.style.transform="")}scrollTarget(t){return t?t===document.scrollingElement?window:t:null}visibleTop(t){return t===document.scrollingElement?0:t.getBoundingClientRect().top}get fieldset(){return this.shadowRoot?.querySelector(".form-control")??null}positionLabel(){if(this.animation)return;let t=this.labelColumn,r=this.fieldset;if(!t||!r)return;let n=0;if(this.tracked&&getComputedStyle(t).position==="sticky"){let a=this.visibleTop(this.tracked),s=t.getBoundingClientRect().top-this.offset,l=Math.max(0,r.clientHeight-t.offsetHeight);n=Math.min(Math.max(a+this.stickyTop-s,0),l)}Math.round(n)!==Math.round(this.offset)&&(this.offset=n,t.style.transform=n?`translateY(${n}px)`:"")}nearestScrollContainer(t){return this.ancestors(t).find(r=>{let n=getComputedStyle(r);return this.isScrollContainer(n.overflowY)||this.isScrollContainer(n.overflowX)})??null}scrollingAncestor(t){let r=this.ancestors(t).find(a=>{let s=getComputedStyle(a).overflowY;return(s==="auto"||s==="scroll"||s==="overlay")&&a.scrollHeight>a.clientHeight+1});if(r)return r;let n=document.scrollingElement;return n&&n.scrollHeight>n.clientHeight+1?n:null}isScrollContainer(t){return t==="auto"||t==="scroll"||t==="hidden"||t==="overlay"}ancestors(t){let r=[],n=t;for(;n;){let a=n instanceof Element&&n.assignedSlot?n.assignedSlot:n.parentNode instanceof ShadowRoot?n.parentNode.host:n.parentNode;a instanceof HTMLElement&&r.push(a),n=a}return r}render(){let t=this.hasSlotController.test("label"),r=this.hasSlotController.test("label-tooltip"),n=this.hasSlotController.test("help-text"),a=this.label?!0:t,s=this.labelTooltip?!0:r,l=this.helpText?!0:n,d=this.hasSlotController.test("chip");return u`
       <fieldset
         part="form-control"
         class="${q({"form-control":!0,"form-control--has-label":a,"form-control--has-label-tooltip":s,"form-control--has-help-text":l,"form-control--pad":this.pad})}"

package/docs/pages/components/form-group.md

@@ -362,7 +362,7 @@ This ensures forms remain usable on all devices without additional configuration
 
 The label column sticks to the top of the scroll container, so on a long form it stays beside the inputs instead of scrolling away. Use the `--zn-form-group-sticky-top` custom property to change the offset it settles at — useful when the scroll container has a sticky header of its own.
 
-A container that clips its overflow but never scrolls — a `zn-panel` body sized to its content, say — would otherwise catch the label and hold it still for the whole scroll. The group clips such a container instead (`overflow: clip`, which clips without being a scroll container), so the label follows the box that is actually scrolled. Scrolling goes straight back to the container the moment its content outgrows it.
+Where a container clips its overflow but never scrolls — a `zn-panel` body sized to its content, say — native sticky anchors to it and the label would sit still for the whole scroll. The group follows the container that is actually scrolled instead, off a scroll timeline where the browser has them so the compositor keeps the label with the fields, and off a scroll handler where it does not.
 
 ```html:preview
 <div style="max-height: 300px; overflow-y: auto;">

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubex/zinc",
-  "version": "1.1.119",
+  "version": "1.1.120",
   "description": "A collection of web components for building web applications based off of @shoelace-style/Shoelace",
   "keywords": [
     "web components",

package/src/components/form-group/form-group.component.ts

@@ -45,16 +45,21 @@ export default class ZnFormGroup extends ZincElement {
 
   @property({ attribute: 'pad', type: Boolean }) pad: boolean = false;
 
-  /** The scroll containers we have clipped, against the inline overflow each carried before. */
-  private readonly clipped = new Map<HTMLElement, { x: string; y: string }>();
+  /** The scroller the label is moved against by hand; null while native sticky is enough. */
+  private tracked: HTMLElement | null = null;
+  /** Set while the compositor is running the movement off a scroll timeline instead. */
+  private animation: Animation | null = null;
+  private stickyTop: number = 0;
   private frame: number = 0;
+  private rebind: boolean = false;
+  private offset: number = 0;
   private resizeObserver: ResizeObserver | null = null;
 
   connectedCallback() {
     super.connectedCallback();
 
     // Whether an ancestor scrolls depends on how tall this form has grown.
-    this.resizeObserver ??= new ResizeObserver(() => this.schedule());
+    this.resizeObserver ??= new ResizeObserver(() => this.schedule(true));
     this.resizeObserver.observe(this);
     window.addEventListener('resize', this.onViewportResize);
   }
@@ -63,93 +68,198 @@ export default class ZnFormGroup extends ZincElement {
     super.disconnectedCallback();
     this.resizeObserver?.disconnect();
     window.removeEventListener('resize', this.onViewportResize);
-    this.release([...this.clipped.keys()]);
+    this.detach();
     cancelAnimationFrame(this.frame);
     this.frame = 0;
   }
 
   protected firstUpdated(changedProperties: PropertyValues) {
     super.firstUpdated(changedProperties);
-    this.schedule();
+    this.schedule(true);
   }
 
   private get labelColumn(): HTMLElement | null {
     return this.shadowRoot?.querySelector('.form-control__text') ?? null;
   }
 
-  /** Coalesces resize work into one frame, and out of the ResizeObserver callback. */
-  private schedule() {
+  /** Coalesces scroll and resize work into one frame, and out of the ResizeObserver callback. */
+  private schedule(rebind: boolean = false) {
+    this.rebind ||= rebind;
     if (this.frame) return;
 
     this.frame = requestAnimationFrame(() => {
       this.frame = 0;
-      this.freeSticky();
+      if (this.rebind) {
+        this.rebind = false;
+        this.bind();
+      }
+      this.positionLabel();
     });
   }
 
-  // A shorter viewport can make an ancestor scroll without changing this form's size.
-  private readonly onViewportResize = () => this.schedule();
-
   /**
-   * Native sticky anchors to the nearest scroll container, even one that cannot scroll — a `zn-panel` body sized to
-   * its content, say — where it then holds the label still for the whole scroll. `overflow: clip` clips without
-   * making a scroll container, so clipping those takes them out of sticky's search and the label follows the box the
-   * user actually scrolls, moved by the compositor rather than by hand.
+   * Native sticky only follows the nearest scroll container. Where that container isn't the one
+   * the user actually scrolls — a `zn-panel` body sized to its content inside a scrolling
+   * slideout, say — the label never moves, so it is moved against the real scroller instead.
    */
-  private freeSticky() {
+  private bind() {
     const column = this.labelColumn;
     if (!column) return;
 
-    const dead: HTMLElement[] = [];
+    // Measured with nothing of ours on the label, so what follows reads its resting position.
+    this.detach();
+    column.style.top = '';
+    this.stickyTop = parseFloat(getComputedStyle(column).top) || 0;
+
+    const anchor = this.nearestScrollContainer(column);
+    if (!anchor) return;
+
+    const scroller = this.scrollingAncestor(column);
+    if (scroller === anchor) return;
+
+    // A `top` inset against a box that never scrolls has nothing to hold the label back from:
+    // it only pushes the label down the page, so drop it and stand in for sticky below.
+    column.style.top = '0px';
+    if (!scroller) return;
+
+    this.tracked = scroller;
+
+    /*
+     * Scrolling is composited, so a transform written from a scroll handler lands a frame late and the label swims
+     * against the fields. A scroll timeline hands the same movement to the compositor; the handler is the fallback
+     * for browsers without one.
+     */
+    this.animation = this.scrollLinkedTravel(scroller);
+    if (this.animation) {
+      this.animation.play();
+      // Content arriving above the form moves the scroll position the label has to start from, and nothing resizes
+      // to say so. Re-measured at the end of a gesture, which is the soonest it can be seen.
+      this.scrollTarget(scroller)?.addEventListener('scrollend', this.onScrollEnd, { passive: true });
+      return;
+    }
 
-    for (const element of this.ancestors(column)) {
-      if (!this.clipped.has(element) && !this.isStickyAnchor(element)) continue;
+    this.scrollTarget(scroller)?.addEventListener('scroll', this.onScroll, { passive: true });
+  }
 
-      // Scroll size reports the overflow through a clip, so a box that has grown into needing to scroll is handed
-      // straight back — and sticky anchors to it, which is now the right answer.
-      if (this.overflows(element)) break;
+  /**
+   * The label's whole journey, as the scroll positions it turns at: still until the fieldset's top reaches the sticky
+   * line, then a pixel for every pixel of scroll until it has crossed the fieldset. `fill: both` holds it at either
+   * end, which is the clamp the scroll handler applies by hand.
+   */
+  private scrollLinkedTravel(scroller: HTMLElement): Animation | null {
+    const column = this.labelColumn;
+    const fieldset = this.fieldset;
+    if (!column || !fieldset || typeof ScrollTimeline === 'undefined') return null;
+
+    // The stylesheet drops sticky while the columns are stacked, and there is nothing to follow.
+    if (getComputedStyle(column).position !== 'sticky') return null;
+
+    const travel = Math.max(0, fieldset.clientHeight - column.offsetHeight);
+    const range = scroller.scrollHeight - scroller.clientHeight;
+    if (travel < 1 || range < 1) return null;
+
+    const start = scroller.scrollTop + column.getBoundingClientRect().top
+      - this.visibleTop(scroller) - this.stickyTop;
+    const held = (scroll: number) => Math.min(Math.max(scroll - start, 0), travel);
+
+    const knees = [start, start + travel].filter(scroll => scroll > 0 && scroll < range);
+    const keyframes = [0, ...knees, range].map(scroll => ({
+      offset: Math.min(Math.max(scroll / range, 0), 1),
+      transform: `translateY(${held(scroll)}px)`
+    }));
+
+    return new Animation(
+      new KeyframeEffect(column, keyframes, { fill: 'both' }),
+      new ScrollTimeline({ source: scroller, axis: 'block' })
+    );
+  }
 
-      dead.push(element);
-    }
+  /** Drops everything this component has put on the label or on the scroller. */
+  private detach() {
+    const target = this.scrollTarget(this.tracked);
+    target?.removeEventListener('scroll', this.onScroll);
+    target?.removeEventListener('scrollend', this.onScrollEnd);
+    this.tracked = null;
+
+    this.animation?.cancel();
+    this.animation = null;
 
-    this.release([...this.clipped.keys()].filter(element => !dead.includes(element)));
-    dead.filter(element => !this.clipped.has(element)).forEach(element => this.clip(element));
+    const column = this.labelColumn;
+    if (!column) return;
+    this.offset = 0;
+    column.style.transform = '';
   }
 
-  private clip(element: HTMLElement) {
-    // A second form group in the same container finds the first one's clip already inline. Recording it as what was
-    // there before would leave the box clipped for good, so it counts as nothing to put back.
-    const kept = (overflow: string) => overflow === 'clip' ? '' : overflow;
-    this.clipped.set(element, { x: kept(element.style.overflowX), y: kept(element.style.overflowY) });
-    element.style.overflowX = 'clip';
-    element.style.overflowY = 'clip';
+  /** The document scrolls through the window, every other scroller reports its own events. */
+  private scrollTarget(scroller: HTMLElement | null): EventTarget | null {
+    if (!scroller) return null;
+    return scroller === document.scrollingElement ? window : scroller;
+  }
 
-    // Scrolling has to go back the moment the box is short enough to need it.
-    this.resizeObserver?.observe(element);
+  /** Where the scroller's own top edge sits, which for the document is the top of the viewport. */
+  private visibleTop(scroller: HTMLElement) {
+    return scroller === document.scrollingElement ? 0 : scroller.getBoundingClientRect().top;
   }
 
-  private release(elements: HTMLElement[]) {
-    elements.forEach(element => {
-      const inline = this.clipped.get(element);
-      element.style.overflowX = inline?.x ?? '';
-      element.style.overflowY = inline?.y ?? '';
-      this.resizeObserver?.unobserve(element);
-      this.clipped.delete(element);
-    });
+  private get fieldset(): HTMLElement | null {
+    return this.shadowRoot?.querySelector('.form-control') ?? null;
+  }
+
+  private readonly onScroll = () => this.schedule();
+
+  private readonly onScrollEnd = () => this.schedule(true);
+
+  // A shorter viewport can make an ancestor scrollable without changing this form's size.
+  private readonly onViewportResize = () => this.schedule(true);
+
+  private positionLabel() {
+    if (this.animation) return;
+
+    const column = this.labelColumn;
+    const fieldset = this.fieldset;
+    if (!column || !fieldset) return;
+
+    let offset = 0;
+
+    // The stylesheet drops sticky while the columns are stacked; tracking has to stand down too.
+    if (this.tracked && getComputedStyle(column).position === 'sticky') {
+      const visibleTop = this.visibleTop(this.tracked);
+      const restingTop = column.getBoundingClientRect().top - this.offset;
+      const travel = Math.max(0, fieldset.clientHeight - column.offsetHeight);
+
+      offset = Math.min(Math.max(visibleTop + this.stickyTop - restingTop, 0), travel);
+    }
+
+    if (Math.round(offset) === Math.round(this.offset)) return;
+
+    this.offset = offset;
+    column.style.transform = offset ? `translateY(${offset}px)` : '';
   }
 
   /** The box native sticky would anchor to, whether or not it can be scrolled. */
-  private isStickyAnchor(element: HTMLElement) {
-    const style = getComputedStyle(element);
-    return this.isScrollContainer(style.overflowY) || this.isScrollContainer(style.overflowX);
+  private nearestScrollContainer(from: HTMLElement): HTMLElement | null {
+    return this.ancestors(from).find(element => {
+      const style = getComputedStyle(element);
+      return this.isScrollContainer(style.overflowY) || this.isScrollContainer(style.overflowX);
+    }) ?? null;
   }
 
-  private isScrollContainer(overflow: string) {
-    return overflow === 'auto' || overflow === 'scroll' || overflow === 'hidden' || overflow === 'overlay';
+  /** The nearest ancestor the user can actually scroll, falling back to the document. */
+  private scrollingAncestor(from: HTMLElement): HTMLElement | null {
+    const scroller = this.ancestors(from).find(element => {
+      const overflow = getComputedStyle(element).overflowY;
+      return (overflow === 'auto' || overflow === 'scroll' || overflow === 'overlay')
+        && element.scrollHeight > element.clientHeight + 1;
+    });
+
+    if (scroller) return scroller;
+
+    const root = document.scrollingElement as HTMLElement | null;
+    return root && root.scrollHeight > root.clientHeight + 1 ? root : null;
   }
 
-  private overflows(element: HTMLElement) {
-    return element.scrollHeight > element.clientHeight + 1 || element.scrollWidth > element.clientWidth + 1;
+  private isScrollContainer(overflow: string) {
+    return overflow === 'auto' || overflow === 'scroll' || overflow === 'hidden' || overflow === 'overlay';
   }
 
   /** Walks the flattened tree, so slots and shadow boundaries are crossed the way layout does. */

package/src/components/form-group/form-group.test.ts

@@ -78,9 +78,8 @@ describe('<zn-form-group>', () => {
     });
 
     it('leaves the label level with the inputs while nothing scrolls', async () => {
-      // Held clear of the viewport's top edge, which sticky's own inset holds the label back from wherever it is.
       const el = await fixture<HTMLElement>(html`
-        <div style="width: 900px; padding-top: 60px">
+        <div style="width: 900px">
           <zn-panel>
             <zn-form-group label="Sticky"><zn-input label="Name"></zn-input></zn-form-group>
           </zn-panel>
@@ -94,23 +93,24 @@ describe('<zn-form-group>', () => {
       expect(label).to.be.closeTo(inputs, 2);
     });
 
-    it('clips a scroll container that cannot scroll, and hands it back when it can', async () => {
+    it('hands the movement to a scroll timeline where the browser has one', async () => {
+      if (!window.ScrollTimeline) return;
+
       const el = await fixture<HTMLElement>(html`
-        <div style="width: 900px; max-height: 300px; overflow-y: auto">
+        <div style="max-height: 300px; overflow-y: auto">
           <zn-panel>
             <zn-form-group label="Sticky"></zn-form-group>
           </zn-panel>
         </div>`);
-      el.querySelector('zn-form-group')!.innerHTML = tallForm;
+      const group = el.querySelector<HTMLElement>('zn-form-group')!;
+      group.innerHTML = tallForm;
       await new Promise(resolve => setTimeout(resolve, 400));
 
-      const body = el.querySelector('zn-panel')!.shadowRoot!.querySelector<HTMLElement>('.panel__body')!;
-      expect(getComputedStyle(body).overflowY, 'sticky has to skip a body that cannot scroll').to.equal('clip');
-
-      body.style.maxHeight = '120px';
-      await new Promise(resolve => setTimeout(resolve, 400));
+      const label = group.shadowRoot!.querySelector<HTMLElement>('.form-control__text')!;
+      const [animation] = label.getAnimations();
 
-      expect(getComputedStyle(body).overflowY, 'and it scrolls again once it must').to.equal('auto');
+      expect(animation, 'the compositor drives the label, not the scroll handler').to.exist;
+      expect(animation.timeline).to.be.instanceOf(window.ScrollTimeline);
     });
 
     it('holds the label in view when a panel sits between the form and the scroll container', async () => {

package/src/declaration.d.ts

@@ -37,3 +37,25 @@ declare interface Window {
 }
 
 /* eslint-enable */
+
+/* eslint-disable */
+interface ScrollTimelineOptions {
+  source?: Element | null;
+  axis?: 'block' | 'inline' | 'x' | 'y';
+}
+
+interface ScrollTimeline extends AnimationTimeline {
+  readonly source: Element | null;
+  readonly axis: string;
+}
+
+declare const ScrollTimeline: {
+  prototype: ScrollTimeline;
+  new(options?: ScrollTimelineOptions): ScrollTimeline;
+};
+
+declare interface Window {
+  ScrollTimeline?: typeof ScrollTimeline;
+}
+
+/* eslint-enable */