@kubex/zinc 1.1.119 → 1.1.121

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/docs/pages/components/translation-group.md

@@ -62,8 +62,8 @@ select's accessible name — it is not shown, since the caption names the sectio
 ### Pre-filled Values
 
 Set initial translations on each child. A language every child has a value for is marked `Translated`; one only some
-children have is `Partial`; one no child has falls back to English. English itself is the source, so it is neither
-counted nor marked as a translation.
+children have is `Partial`; one no child has falls back to English. English itself is marked `Empty` rather than
+falling back, having nothing to fall back to, and counts towards the total like any other language.
 
 ```html:preview
 <zn-translation-group

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubex/zinc",
-  "version": "1.1.119",
+  "version": "1.1.121",
   "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/components/translation-group/translation-group.component.ts

@@ -32,8 +32,8 @@ import styles from './translation-group.scss';
  * - `Partial` — only some children do
  * - `English` — none do, so all of them fall back to the English text
  *
- * `Empty` replaces the last of those for English itself, which has nothing to fall back to. English is the source
- * rather than a translation, so it is also left out of the `n of m translated` count beside the label.
+ * `Empty` replaces the last of those for English itself, which has nothing to fall back to. English counts towards
+ * the `n of m` beside the label like any other language.
  *
  * The children own their values; this component only chooses which language is shown and reports on what they hold.
  * It reads them back on every child `zn-change`, so the chips and the count follow an edit as it is typed.
@@ -221,14 +221,12 @@ export default class ZnTranslationGroup extends ZnPanel {
     const languageCodes = [...Object.keys(this.languages), ...extra];
     const hasMultipleLanguages = languageCodes.length > 1;
 
-    // English is the source every other language falls back to, so it is not itself one of the translations counted.
-    const targets = languageCodes.filter(code => code !== 'en');
-    const translated = targets.filter(code => this.languageState(code).type === 'success').length;
     // Closed, the select answers "how much is left to do" rather than the state of the one language on show — that
     // is what the options are for.
+    const translated = languageCodes.filter(code => this.languageState(code).type === 'success').length;
     const summary = {
-      label: `${translated}/${targets.length}`,
-      type: translated === targets.length ? 'success' : translated > 0 ? 'warning' : 'error'
+      label: `${translated}/${languageCodes.length}`,
+      type: translated === languageCodes.length ? 'success' : translated > 0 ? 'warning' : 'error'
     };
 
     return html`

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

@@ -188,7 +188,7 @@ describe('<zn-translation-group>', () => {
       expect(label.textContent?.trim(), 'nothing else rides the caption').to.equal('Content');
 
       const summary = selectOf(group).querySelector('zn-chip[slot="suffix"]')!;
-      expect(summary.textContent?.trim()).to.equal('1/1');
+      expect(summary.textContent?.trim()).to.equal('2/2');
     });
 
     it('wears the same chrome as any other select', async () => {
@@ -327,19 +327,19 @@ describe('<zn-translation-group>', () => {
         ['{"en":"Hello","fr":"Bonjour","de":"Hallo"}', '{"en":"Hi","fr":"Salut"}']);
 
       const summary = selectOf(group).querySelector('zn-chip[slot="suffix"]')!;
-      expect(summary.textContent?.trim()).to.equal('1/3');
+      expect(summary.textContent?.trim()).to.equal('2/4');
       expect(summary.getAttribute('type')).to.equal('warning');
 
       expect(chipsOf(group)).to.deep.equal(['Translated', 'Translated', 'Partial', 'English']);
     });
 
-    it('marks the summary chip done once every target language is translated', async () => {
+    it('marks the summary chip done once every language is translated', async () => {
       const group = await groupFixture(
         {en: 'English', fr: 'French'},
         ['{"en":"Hello","fr":"Bonjour"}']);
 
       const summary = selectOf(group).querySelector('zn-chip[slot="suffix"]')!;
-      expect(summary.textContent?.trim()).to.equal('1/1');
+      expect(summary.textContent?.trim()).to.equal('2/2');
       expect(summary.getAttribute('type')).to.equal('success');
     });
 
@@ -351,13 +351,13 @@ describe('<zn-translation-group>', () => {
       expect(chipsOf(group)).to.deep.equal(['Translated', 'English']);
     });
 
-    it('counts the target languages, not English', async () => {
+    it('counts English alongside the target languages', async () => {
       const group = await groupFixture(
         {en: 'English', fr: 'French', de: 'German'},
         ['{"en":"Hello","fr":"Bonjour"}']);
 
       const summary = selectOf(group).querySelector('zn-chip[slot="suffix"]')!;
-      expect(summary.textContent?.trim()).to.equal('1/2');
+      expect(summary.textContent?.trim()).to.equal('2/3');
     });
 
     it('switches every child when the select changes', async () => {
@@ -416,14 +416,14 @@ describe('<zn-translation-group>', () => {
       await group.updateComplete;
 
       const summary = () => group.shadowRoot!.querySelector('zn-select zn-chip[slot="suffix"]')!.textContent?.trim();
-      expect(summary()).to.equal('0/1');
+      expect(summary()).to.equal('1/2');
 
       form.reset();
       await new Promise(resolve => requestAnimationFrame(() => resolve(null)));
       await group.updateComplete;
 
       expect(child.values).to.deep.equal({en: 'Hello', fr: 'Bonjour'});
-      expect(summary()).to.equal('1/1');
+      expect(summary()).to.equal('2/2');
     });
   });
 });

package/src/components/translations/translations.component.ts

@@ -445,11 +445,10 @@ export default class ZnTranslations extends ZincElement implements ZincFormContr
     ];
     // Closed, the select answers "how much is left to do" rather than the state of the one language on show — that
     // is what the options are for.
-    const targets = languageCodes.filter(code => code !== 'en');
-    const translated = targets.filter(code => this.hasTranslation(code)).length;
+    const translated = languageCodes.filter(code => this.hasTranslation(code)).length;
     const summary = {
-      label: `${translated}/${targets.length}`,
-      type: translated === targets.length ? 'success' : translated > 0 ? 'warning' : 'error'
+      label: `${translated}/${languageCodes.length}`,
+      type: translated === languageCodes.length ? 'success' : translated > 0 ? 'warning' : 'error'
     };
 
     const currentTranslation = this.values[this._activeLanguage] ?? '';

package/src/components/translations/translations.test.ts

@@ -95,7 +95,7 @@ describe('<zn-translations>', () => {
       await el.updateComplete;
 
       const summary = selectOf(el)!.querySelector('zn-chip[slot="suffix"]')!;
-      expect(summary.textContent?.trim()).to.equal('1/2');
+      expect(summary.textContent?.trim()).to.equal('2/3');
       expect(summary.getAttribute('type')).to.equal('warning');
 
       const options = [...selectOf(el)!.querySelectorAll('zn-option zn-chip')];

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 */