@kubex/zinc 1.1.116 → 1.1.118

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

@@ -358,27 +358,60 @@ This ensures forms remain usable on all devices without additional configuration
 </zn-form-group>
 ```
 
+### Sticky Label
+
+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.
+
+```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">
+    <zn-input label="Recipient" placeholder="Full name"></zn-input>
+    <zn-input label="Street Address" placeholder="123 Main Street"></zn-input>
+    <zn-input label="Apartment/Unit" placeholder="Apt 4B"></zn-input>
+    <zn-input label="City" placeholder="New York"></zn-input>
+    <zn-input label="Postal Code" placeholder="10001"></zn-input>
+    <zn-input label="Phone" type="tel" placeholder="(555) 123-4567"></zn-input>
+    <zn-textarea label="Delivery Notes" placeholder="Leave with the concierge..." rows="4"></zn-textarea>
+  </zn-form-group>
+</div>
+```
+
 ### Styling with CSS Parts
 
-Form groups expose several CSS parts that can be styled to customize their appearance. This example demonstrates how to create custom layouts using CSS grid.
+Form groups expose several CSS parts that can be styled to customize their appearance. `form-control-text` is the column holding the label, help text and chip — it is the part that sticks as the fields scroll, so give it the same background as the group to stop the fields showing through underneath it.
 
 ```html:preview
-<zn-form-group class="custom-form-group" label="Custom Styled Form Group" help-text="This form group has custom spacing and borders">
-  <zn-input label="Field 1" span="3"></zn-input>
-  <zn-input label="Field 2" span="3"></zn-input>
-  <zn-input label="Field 3" span="2"></zn-input>
-  <zn-input label="Field 4" span="2"></zn-input>
-  <zn-input label="Field 5" span="2"></zn-input>
-</zn-form-group>
+<div class="custom-form-group-scroller">
+  <zn-form-group class="custom-form-group" label="Custom Styled Form Group" help-text="This form group has custom spacing and borders">
+    <zn-input label="Field 1" span="3"></zn-input>
+    <zn-input label="Field 2" span="3"></zn-input>
+    <zn-input label="Field 3" span="2"></zn-input>
+    <zn-input label="Field 4" span="2"></zn-input>
+    <zn-input label="Field 5" span="2"></zn-input>
+    <zn-input label="Field 6" span="3"></zn-input>
+    <zn-input label="Field 7" span="3"></zn-input>
+    <zn-textarea label="Field 8" rows="4"></zn-textarea>
+  </zn-form-group>
+</div>
 
 <style>
+  .custom-form-group-scroller {
+    max-height: 320px;
+    overflow-y: auto;
+  }
+
   .custom-form-group::part(form-control) {
-    padding: var(--zn-spacing-large);
+    padding: var(--zn-spacing-medium);
     border: 2px solid var(--zn-color-primary-300);
     border-radius: var(--zn-border-radius);
     background-color: var(--zn-color-primary-50);
   }
 
+  .custom-form-group::part(form-control-text) {
+    padding-bottom: var(--zn-spacing-small);
+    background-color: var(--zn-color-primary-50);
+  }
+
   .custom-form-group::part(form-control-label) {
     color: var(--zn-color-primary-700);
   }

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.116",
+  "version": "1.1.118",
   "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

@@ -1,5 +1,5 @@
 import { classMap } from "lit/directives/class-map.js";
-import { type CSSResultGroup, html, unsafeCSS } from 'lit';
+import { type CSSResultGroup, html, type PropertyValues, unsafeCSS } from 'lit';
 import { HasSlotController } from "../../internal/slot";
 import { property } from 'lit/decorators.js';
 import ZincElement from '../../internal/zinc-element';
@@ -16,6 +16,10 @@ import styles from './form-group.scss';
  * @slot - The default slot.
  * @slot chip - A chip displayed under the form group's help text.
  *
+ * @csspart form-control-text - The column holding the label, help text and chip.
+ *
+ * @cssproperty --zn-form-group-sticky-top - Offset the label column sticks at while the inputs scroll past.
+ *
  */
 export default class ZnFormGroup extends ZincElement {
   static styles: CSSResultGroup = [unsafeCSS(formControlStyles), unsafeCSS(styles)];
@@ -41,6 +45,165 @@ 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;
+  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.observe(this);
+    window.addEventListener('resize', this.onViewportResize);
+  }
+
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    this.resizeObserver?.disconnect();
+    window.removeEventListener('resize', this.onViewportResize);
+    this.trackScroller(null);
+    cancelAnimationFrame(this.frame);
+    this.frame = 0;
+  }
+
+  protected firstUpdated(changedProperties: PropertyValues) {
+    super.firstUpdated(changedProperties);
+    this.schedule(true);
+  }
+
+  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;
+    if (this.frame) return;
+
+    this.frame = requestAnimationFrame(() => {
+      this.frame = 0;
+      if (this.rebind) {
+        this.rebind = false;
+        this.findScroller();
+      }
+      this.positionLabel();
+    });
+  }
+
+  /**
+   * 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.
+   */
+  private findScroller() {
+    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();
+
+  // 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;
+
+    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);
+
+      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 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;
+  }
+
+  /** 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 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. */
+  private ancestors(from: HTMLElement): HTMLElement[] {
+    const out: HTMLElement[] = [];
+    let node: Node | null = from;
+
+    while (node) {
+      const parent: Node | null = node instanceof Element && node.assignedSlot
+        ? node.assignedSlot
+        : node.parentNode instanceof ShadowRoot ? node.parentNode.host : node.parentNode;
+
+      if (parent instanceof HTMLElement) out.push(parent);
+      node = parent;
+    }
+
+    return out;
+  }
+
   render() {
     const hasLabelSlot = this.hasSlotController.test('label');
     const hasLabelTooltipSlot = this.hasSlotController.test('label-tooltip');
@@ -65,7 +228,7 @@ export default class ZnFormGroup extends ZincElement {
 
         <zn-cols layout="${this.layout}" part="form-control-container" class="form-control__container">
           ${hasLabel || hasHelpText || hasChip || this.forceCols ? html`
-            <div class="form-control__text">
+            <div part="form-control-text" class="form-control__text">
 
               ${hasLabel ? html`
                 <label

package/src/components/form-group/form-group.scss

@@ -4,7 +4,8 @@
   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-col-gap: calc(var(--zn-spacing-medium, 20px) * 3);
+  --zn-form-group-sticky-top: var(--zn-spacing-medium, 20px);
 }
 
 .form-control {
@@ -27,6 +28,18 @@
   --zn-col-basis: 200px;
 }
 
+// Only while the label sits beside the inputs: once zn-cols wraps them into one column a sticky
+// label would scroll over the fields it labels. zn-cols wraps below the two columns' bases plus
+// the gap, so 670px = --zn-col-basis * (1 + 2) + 70px — keep in step with both values below.
+@container (min-width: 670px) {
+  .form-control__text {
+    position: sticky;
+    top: var(--zn-form-group-sticky-top);
+    // A stretched flex item is as tall as the row, leaving sticky nothing to travel through.
+    align-self: flex-start;
+  }
+}
+
 .form-control__chip {
   margin-top: var(--zn-spacing-x-small);
 }
@@ -45,11 +58,13 @@
 
 .form-control-input {
   display: grid;
-  grid-template-columns: 1fr;
+  grid-template-columns: minmax(0, 1fr);
   gap: var(--zn-spacing-medium) var(--zn-spacing-small);
 
+  // `1fr` floors each track at its min-content width, so one long label steals width from
+  // the other tracks and the spans stop lining up.
   @include wc.media-query(md) {
-    grid-template-columns: repeat(6, 1fr);
+    grid-template-columns: repeat(6, minmax(0, 1fr));
   }
 }
 

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

@@ -26,4 +26,84 @@ describe('<zn-form-group>', () => {
 
     expect(el.shadowRoot!.querySelector('[part="form-control-chip"]')).to.not.exist;
   });
+
+  describe('sticky label', () => {
+    const tallForm = Array.from({length: 25}, (_, i) => `<zn-input label="Field ${i}"></zn-input>`).join('');
+
+    async function scrollPast(group: HTMLElement) {
+      group.innerHTML = tallForm;
+      await new Promise(resolve => setTimeout(resolve, 400));
+
+      const label = group.shadowRoot!.querySelector<HTMLElement>('.form-control__text')!;
+      const before = label.getBoundingClientRect().top;
+
+      for (let node: Node | null = label; node; node = flatParent(node)) {
+        if (node instanceof HTMLElement && node.scrollHeight > node.clientHeight + 1) node.scrollTop = 500;
+      }
+      await new Promise(resolve => setTimeout(resolve, 200));
+
+      return {before, after: label.getBoundingClientRect().top};
+    }
+
+    function flatParent(node: Node): Node | null {
+      if (node instanceof Element && node.assignedSlot) return node.assignedSlot;
+      return node.parentNode instanceof ShadowRoot ? node.parentNode.host : node.parentNode;
+    }
+
+    it('holds the label in view when the scroll container is the nearest one', async () => {
+      const el = await fixture<HTMLElement>(html`
+        <div style="max-height: 300px; overflow-y: auto">
+          <zn-form-group label="Sticky"></zn-form-group>
+        </div>`);
+
+      const {before, after} = await scrollPast(el.querySelector('zn-form-group')!);
+
+      expect(after).to.be.closeTo(before, 4);
+    });
+
+    it('gives up sticky once the columns stack', async () => {
+      const wide = await fixture<HTMLElement>(html`
+        <div style="width: 900px"><zn-form-group label="Sticky"></zn-form-group></div>`);
+      const narrow = await fixture<HTMLElement>(html`
+        <div style="width: 500px"><zn-form-group label="Sticky"></zn-form-group></div>`);
+      await new Promise(resolve => setTimeout(resolve, 100));
+
+      const position = (root: HTMLElement) => {
+        const group = root.querySelector('zn-form-group')!;
+        return getComputedStyle(group.shadowRoot!.querySelector('.form-control__text')!).position;
+      };
+
+      expect(position(wide)).to.equal('sticky');
+      expect(position(narrow)).to.equal('static');
+    });
+
+    it('leaves the label level with the inputs while nothing scrolls', async () => {
+      const el = await fixture<HTMLElement>(html`
+        <div style="width: 900px">
+          <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('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">
+          <zn-panel>
+            <zn-form-group label="Sticky"></zn-form-group>
+          </zn-panel>
+        </div>`);
+
+      const {before, after} = await scrollPast(el.querySelector('zn-form-group')!);
+
+      expect(after).to.be.closeTo(before, 4);
+    });
+  });
 });