@kubex/zinc 1.1.117 → 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/docs/pages/components/translation-group.md

@@ -6,13 +6,16 @@ layout: component
 ---
 
 The Translation Group component wraps multiple `zn-translations` components in a panel-styled container with a shared
-language select. The select sits at the top right of the header, opposite the caption. Closed, it carries how many
-languages are done as a `1/5` chip; open, each language is marked translated, partial or falling back to English.
-Choosing a language switches every child at once.
+language select. The fields sit in a [form group](/components/form-group), so the caption, help text and the select
+share its label column and the fields line up with every other form group around them. Closed, the select carries how
+many languages are done as a `1/5` chip; open, each language is marked translated, partial or falling back to English.
+Type to filter the list — by name or by language code, so `de` finds German. Choosing a language switches every child
+at once.
 
 ```html:preview
 <zn-translation-group
   label="Product Content"
+  help-text="Every field is translated one language at a time"
   languages='{"en":"English","fr":"French","de":"German"}'>
   <zn-translations
     label="Name"
@@ -40,14 +43,16 @@ A translation group with two translation inputs sharing one language select.
 </zn-translation-group>
 ```
 
-### With Label
+### Label and Help Text
 
-Use the `label` attribute to add a caption on the left of the header, opposite the language select. `language-label`
-sets the select's accessible name — it is not shown, since the caption names the section on screen.
+`label` names the section in the form group's label column, and `help-text` sits under it — the pair behave as they do
+on any other form group. The language select follows them, in the group's chip position. `language-label` sets the
+select's accessible name — it is not shown, since the caption names the section on screen.
 
 ```html:preview
 <zn-translation-group
   label="Page Translations"
+  help-text="Pick a language to edit every field in it"
   languages='{"en":"English","fr":"French","es":"Spanish"}'>
   <zn-translations label="Heading" name="heading"></zn-translations>
   <zn-translations label="Body" name="body"></zn-translations>
@@ -209,7 +214,8 @@ The group emits a `zn-language-change` event when the active language changes.
 
 | Property         | Type                     | Default            | Description                                       |
 |------------------|--------------------------|--------------------|---------------------------------------------------|
-| `label`          | `string`                 | `''`               | Caption displayed in the panel header             |
+| `label`          | `string`                 | `''`               | Names the section, in the form group's label column |
+| `help-text`      | `string`                 | `''`               | Sits under the label, above the language select   |
 | `language-label` | `string`                 | `'Edit Languages'` | The select's accessible name; not shown on screen |
 | `inline`         | `boolean`                | `false`            | Drops the panel border, background and padding    |
 | `languages`      | `Record<string, string>` | `{en: "EN"}`       | Object mapping language codes to display names    |
@@ -226,19 +232,15 @@ The group emits a `zn-language-change` event when the active language changes.
 | Slot      | Description                                                |
 |-----------|------------------------------------------------------------|
 | (default) | Place `<zn-translations>` elements here                    |
-| `label`   | Alternative to the `label` attribute for rich HTML content |
 | `actions` | Buttons for the bottom of the body; `align="start"` on a child moves it to the left |
 | `footer`  | Content displayed in the grey panel footer                |
 
-The header carries the caption and the language select alone; nothing else is slotted into it.
-
 ## CSS Parts
 
-| Part              | Description                                                     |
-|-------------------|-----------------------------------------------------------------|
-| `base`            | The outer panel wrapper                                         |
-| `header`          | The header area containing the caption and the language select  |
-| `language-field`  | The container holding the language select                       |
-| `language-select` | The select itself                                               |
-| `actions`         | The row of buttons at the bottom of the body                    |
-| `translations`    | The body container wrapping the slotted children                |
+| Part              | Description                                                          |
+|-------------------|----------------------------------------------------------------------|
+| `base`            | The outer panel wrapper                                              |
+| `form-group`      | The form group holding the caption, the language select and the fields |
+| `language-field`  | The container holding the language select, in the group's chip slot   |
+| `language-select` | The select itself                                                    |
+| `actions`         | The row of buttons at the bottom of the body                         |

package/docs/pages/components/translations.md

@@ -128,8 +128,9 @@ Add `inline-edit` to read the translation as text until it is clicked, through
 
 ### Many Languages
 
-Each language becomes an option labelled `Name (CODE)` — or the code alone where the configured name already is the
-code. The select takes any number of them, and its listbox scrolls once the list is longer than the space below it.
+Each language becomes an option labelled with its configured name — or its code, where `languages` does not name it.
+The select takes any number of them, and its listbox scrolls once the list is longer than the space below it. Type to
+filter the list: matching runs over the code as well as the name, so `de` finds German.
 
 ```html:preview
 <zn-translations

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubex/zinc",
-  "version": "1.1.117",
+  "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,18 +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;
+  /** 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);
   }
@@ -65,119 +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;
 
-    const anchor = this.nearestScrollContainer(column);
-    const scroller = anchor ? this.scrollingAncestor(column) : null;
-    this.trackScroller(scroller === anchor ? null : scroller);
-  }
-
-  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);
-
-  private positionLabel() {
-    const column = this.labelColumn;
-    const fieldset = this.shadowRoot?.querySelector<HTMLElement>('.form-control');
-    if (!column || !fieldset) return;
+    for (const element of this.ancestors(column)) {
+      if (!this.clipped.has(element) && !this.isStickyAnchor(element)) continue;
 
-    let offset = 0;
+      // 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 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 stickyTop = parseFloat(getComputedStyle(column).top) || 0;
-      const restingTop = column.getBoundingClientRect().top - this.offset;
-      const travel = Math.max(0, fieldset.clientHeight - column.offsetHeight);
-
-      offset = Math.min(Math.max(visibleTop + 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

@@ -77,6 +77,42 @@ describe('<zn-form-group>', () => {
       expect(position(narrow)).to.equal('static');
     });
 
+    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">
+          <zn-panel>
+            <zn-form-group label="Sticky"><zn-input label="Name"></zn-input></zn-form-group>
+          </zn-panel>
+        </div>`);
+      await new Promise(resolve => setTimeout(resolve, 100));
+
+      const root = el.querySelector('zn-form-group')!.shadowRoot!;
+      const label = root.querySelector('.form-control__text')!.getBoundingClientRect().top;
+      const inputs = root.querySelector('.form-control-input')!.getBoundingClientRect().top;
+
+      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'}},
 ];