@kubex/zinc 1.1.118 → 1.1.119

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

@@ -362,6 +362,8 @@ 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.
+
 ```html:preview
 <div style="max-height: 300px; overflow-y: auto;">
   <zn-form-group label="Delivery Details" help-text="This label follows the inputs as you scroll">

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubex/zinc",
-  "version": "1.1.118",
+  "version": "1.1.119",
   "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,19 +45,16 @@ export default class ZnFormGroup extends ZincElement {
 
   @property({ attribute: 'pad', type: Boolean }) pad: boolean = false;
 
-  /** The scroller the label is tracked against by hand; null while native sticky is enough. */
-  private tracked: HTMLElement | null = null;
-  private stickyTop: number = 0;
+  /** The scroll containers we have clipped, against the inline overflow each carried before. */
+  private readonly clipped = new Map<HTMLElement, { x: string; y: string }>();
   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(true));
+    this.resizeObserver ??= new ResizeObserver(() => this.schedule());
     this.resizeObserver.observe(this);
     window.addEventListener('resize', this.onViewportResize);
   }
@@ -66,127 +63,95 @@ export default class ZnFormGroup extends ZincElement {
     super.disconnectedCallback();
     this.resizeObserver?.disconnect();
     window.removeEventListener('resize', this.onViewportResize);
-    this.trackScroller(null);
+    this.release([...this.clipped.keys()]);
     cancelAnimationFrame(this.frame);
     this.frame = 0;
   }
 
   protected firstUpdated(changedProperties: PropertyValues) {
     super.firstUpdated(changedProperties);
-    this.schedule(true);
+    this.schedule();
   }
 
   private get labelColumn(): HTMLElement | null {
     return this.shadowRoot?.querySelector('.form-control__text') ?? null;
   }
 
-  /** Coalesces scroll and resize work into one frame, and out of the ResizeObserver callback. */
-  private schedule(rebind: boolean = false) {
-    this.rebind ||= rebind;
+  /** Coalesces resize work into one frame, and out of the ResizeObserver callback. */
+  private schedule() {
     if (this.frame) return;
 
     this.frame = requestAnimationFrame(() => {
       this.frame = 0;
-      if (this.rebind) {
-        this.rebind = false;
-        this.findScroller();
-      }
-      this.positionLabel();
+      this.freeSticky();
     });
   }
 
+  // A shorter viewport can make an ancestor scroll without changing this form's size.
+  private readonly onViewportResize = () => this.schedule();
+
   /**
-   * 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 gets translated by hand instead.
+   * 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 findScroller() {
+  private freeSticky() {
     const column = this.labelColumn;
     if (!column) return;
 
-    column.style.top = '';
-    this.stickyTop = parseFloat(getComputedStyle(column).top) || 0;
-
-    const anchor = this.nearestScrollContainer(column);
-    const scroller = anchor ? this.scrollingAncestor(column) : null;
-    const anchored = !anchor || scroller === anchor;
-
-    this.trackScroller(anchored ? null : scroller);
-
-    // 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 let the transform do the work.
-    if (!anchored) column.style.top = '0px';
-  }
-
-  private trackScroller(scroller: HTMLElement | null) {
-    if (scroller === this.tracked) return;
-
-    this.scrollTarget(this.tracked)?.removeEventListener('scroll', this.onScroll);
-    this.tracked = scroller;
-    this.scrollTarget(this.tracked)?.addEventListener('scroll', this.onScroll, { passive: true });
-  }
-
-  /** 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;
-  }
-
-  private readonly onScroll = () => this.schedule();
+    const dead: HTMLElement[] = [];
 
-  // A shorter viewport can make an ancestor scrollable without changing this form's size.
-  private readonly onViewportResize = () => this.schedule(true);
+    for (const element of this.ancestors(column)) {
+      if (!this.clipped.has(element) && !this.isStickyAnchor(element)) continue;
 
-  private positionLabel() {
-    const column = this.labelColumn;
-    const fieldset = this.shadowRoot?.querySelector<HTMLElement>('.form-control');
-    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.tracked === document.scrollingElement
-        ? 0
-        : this.tracked.getBoundingClientRect().top;
-      const restingTop = column.getBoundingClientRect().top - this.offset;
-      const travel = Math.max(0, fieldset.clientHeight - column.offsetHeight);
+      // 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;
 
-      offset = Math.min(Math.max(visibleTop + this.stickyTop - restingTop, 0), travel);
+      dead.push(element);
     }
 
-    if (Math.round(offset) === Math.round(this.offset)) return;
-
-    this.offset = offset;
-    column.style.transform = offset ? `translateY(${offset}px)` : '';
+    this.release([...this.clipped.keys()].filter(element => !dead.includes(element)));
+    dead.filter(element => !this.clipped.has(element)).forEach(element => this.clip(element));
   }
 
-  /** The box native sticky would anchor to, whether or not it can be scrolled. */
-  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 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';
+
+    // Scrolling has to go back the moment the box is short enough to need it.
+    this.resizeObserver?.observe(element);
   }
 
-  /** 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;
+  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);
     });
+  }
 
-    if (scroller) return scroller;
-
-    const root = document.scrollingElement as HTMLElement | null;
-    return root && root.scrollHeight > root.clientHeight + 1 ? root : null;
+  /** 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 isScrollContainer(overflow: string) {
     return overflow === 'auto' || overflow === 'scroll' || overflow === 'hidden' || overflow === 'overlay';
   }
 
+  private overflows(element: HTMLElement) {
+    return element.scrollHeight > element.clientHeight + 1 || element.scrollWidth > element.clientWidth + 1;
+  }
+
   /** Walks the flattened tree, so slots and shadow boundaries are crossed the way layout does. */
   private ancestors(from: HTMLElement): HTMLElement[] {
     const out: HTMLElement[] = [];

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

@@ -78,8 +78,9 @@ 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">
+        <div style="width: 900px; padding-top: 60px">
           <zn-panel>
             <zn-form-group label="Sticky"><zn-input label="Name"></zn-input></zn-form-group>
           </zn-panel>
@@ -93,6 +94,25 @@ 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 () => {
+      const el = await fixture<HTMLElement>(html`
+        <div style="width: 900px; 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;
+      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));
+
+      expect(getComputedStyle(body).overflowY, 'and it scrolls again once it must').to.equal('auto');
+    });
+
     it('holds the label in view when a panel sits between the form and the scroll container', async () => {
       const el = await fixture<HTMLElement>(html`
         <div style="max-height: 300px; overflow-y: auto">

package/src/components/remarkd-editor/actions.ts

@@ -25,7 +25,7 @@ export interface EditorAction {
   /** Where the caret lands within `prefix`. Defaults to the end. */
   caretOffset?: number;
   /** Actions that open their own picker instead of inserting text. */
-  opens?: 'image' | 'include';
+  opens?: 'image' | 'include' | 'link';
 }
 
 /** Toolbar order, most-used first — the last groups are the first to collapse. */
@@ -128,6 +128,7 @@ export const EDITOR_ACTIONS: EditorAction[] = [
   {key: 'tooltip', label: 'Tooltip', icon: 'message-circle-question-mark@lu', group: 'inline', keywords: ['term'], inline: {before: '{', after: '}(Explanation)', placeholder: 'Term'}},
   {key: 'cross-reference', label: 'Cross reference', icon: 'link-2@lu', group: 'inline', keywords: ['xref'], inline: {before: '<<', after: '>>', placeholder: 'section,Label'}},
   {key: 'links-and-images', label: 'Link', icon: 'link@lu', group: 'inline', inline: {before: '[', after: '](https://)', placeholder: 'Label'}},
+  {key: 'document-link', label: 'Link to article', icon: 'file-symlink@lu', group: 'inline', keywords: ['article', 'document', 'kb'], opens: 'link'},
   {key: 'passthrough', label: 'Passthrough', icon: 'shield@lu', group: 'inline', keywords: ['raw', 'literal'], inline: {before: 'pass:[', after: ']', placeholder: 'raw'}},
   {key: 'curly-bang-passthrough', label: 'Literal braces', icon: 'braces@lu', group: 'inline', inline: {before: '{!', after: '!}', placeholder: 'raw'}},
 ];