@kubex/zinc 1.1.81 → 1.1.83

package/docs/pages/components/cols.md

@@ -3,6 +3,7 @@ meta:
   title: Cols
   description: A flexible column layout component that distributes children across multiple columns with configurable layouts, gaps, borders, and padding options.
 layout: component
+fullWidth: true
 ---
 
 ```html:preview
@@ -74,6 +75,48 @@ The layout pattern repeats for additional children. With "2,1", items cycle thro
 </zn-cols>
 ```
 
+### Stacking Order
+
+Use `stack-at` to name the container width the columns collapse to a single column below, as one of
+the container sizes (`sm`, `smp`, `ph`, `md`, `lg`, `hd`, `3k`, `4k`). Children can then declare a
+`stack-order` to say where they belong in that single column, which lets a sidebar sit second in the
+markup but move to the top once stacked.
+
+`stack-order` takes `first`/`high` (before unordered children), `last`/`low` (after them), or any
+integer for finer control. It has no effect while the columns are side by side, so the reading order
+of your markup is what wide screens get.
+
+```html:preview
+<zn-cols layout="2,1" stack-at="md">
+  <zn-panel>Main content — first in the markup, second when stacked</zn-panel>
+  <zn-panel stack-order="first">Sidebar — second in the markup, first when stacked</zn-panel>
+</zn-cols>
+```
+
+### Splitting a Column by Priority
+
+Add `stack-split` to a column to break it apart when stacked. Its children stay together as one
+column on wide screens, then each becomes a column in its own right and takes its own `stack-order`,
+so high priority content can move above the main column while low priority content drops below it.
+
+```html:preview
+<zn-cols layout="2,1" stack-at="md">
+  <zn-panel>Databases — the main column</zn-panel>
+  <div stack-split>
+    <zn-panel stack-order="high">Usage — above the main column when stacked</zn-panel>
+    <zn-panel stack-order="low">Tutorials — below the main column when stacked</zn-panel>
+  </div>
+</zn-cols>
+```
+
+Keep `stack-split` on a plain wrapper element rather than a component: `zn-cols` lays it out as a
+column (`display: flex` in a column, with the standard gap) and then removes its box entirely while
+stacked, so any styling of its own would disappear along with it.
+
+`stack-at` defaults to `lg` when any child declares `stack-order` or `stack-split`. Set it explicitly
+at or above the width where your columns would otherwise wrap on their own, so that reordering is
+already in effect by the time the layout breaks.
+
 ### With Borders
 
 Use the `border` attribute to add borders around columns.

package/docs/pages/components/translations.md

@@ -323,6 +323,22 @@ A complete example showing product content management with translations.
 </div>
 ```
 
+### Help Text
+
+Use the `help-text` attribute to describe how the field should be filled in. It sits below the field and applies to
+every language, so it is the place to explain a convention the translator needs to follow. For help text containing
+HTML, use the `help-text` slot instead.
+
+```html:preview
+<zn-translations
+  label="Confirmation headline"
+  help-text="Keep this under 60 characters so it does not wrap on mobile."></zn-translations>
+<br />
+<zn-translations label="Footer">
+  <div slot="help-text">Shown on <strong>every</strong> page of the checkout.</div>
+</zn-translations>
+```
+
 ### Slash Menu Quick Insertions
 
 {% raw %}
@@ -360,6 +376,7 @@ way `Enter` otherwise would.
 | `name`      | `string`                    | `''`            | Form field name for submission                                       |
 | `value`     | `string`                    | `'{"en":""}'`   | JSON string of translations                                          |
 | `label`     | `string`                    | `''`            | Label displayed above the component                                  |
+| `help-text` | `string`                    | `''`            | Text shown below the field, describing how to fill it in             |
 | `disabled`  | `boolean`                   | `false`         | Disables editing of all translations                                 |
 | `required`  | `boolean`                   | `false`         | Makes the field required for form validation                         |
 | `flush`     | `boolean`                   | `false`         | Removes padding for compact layout                                   |
@@ -379,10 +396,11 @@ way `Enter` otherwise would.
 
 ## Slots
 
-| Slot      | Description                                                      |
-|-----------|------------------------------------------------------------------|
-| `label`   | Alternative to the `label` attribute for rich HTML content       |
-| `expand`  | Action button displayed in the navbar (e.g., translate button)   |
+| Slot        | Description                                                      |
+|-------------|------------------------------------------------------------------|
+| `label`     | Alternative to the `label` attribute for rich HTML content       |
+| `expand`    | Action button displayed in the navbar (e.g., translate button)   |
+| `help-text` | Alternative to the `help-text` attribute for rich HTML content   |
 
 ## Methods
 

package/package.json

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

package/src/components/cols/cols.component.ts

@@ -5,6 +5,18 @@ import ZincElement from '../../internal/zinc-element';
 
 import styles from './cols.scss';
 
+/**
+ * Priority keywords accepted by the `stack-order` attribute on children.
+ */
+const STACK_ORDER_KEYWORDS: Record<string, number> = {
+  first: -1,
+  high: -1,
+  last: 1,
+  low: 1,
+};
+
+const DEFAULT_STACK_AT = 'lg';
+
 /**
  * @summary Short summary of the component's intended use.
  * @documentation https://zinc.style/components/columns
@@ -27,6 +39,13 @@ export default class ZnCols extends ZincElement {
 
   @property({reflect: true, attribute: 'layout'}) layout: string = '';
 
+  /**
+   * Container width the columns collapse to a single column below, as one of the named zinc
+   * container sizes (sm, smp, ph, md, lg, hd, 3k, 4k). Defaults to `lg` when a child declares
+   * `stack-order` or `stack-split`, otherwise the columns never explicitly stack.
+   */
+  @property({attribute: 'stack-at', reflect: true}) stackAt: string = '';
+
   @property({attribute: 'mc', type: Number, reflect: true}) maxColumns: number = 0;
 
   @property({attribute: 'no-gap', type: Boolean}) noGap: boolean = false;
@@ -41,6 +60,52 @@ export default class ZnCols extends ZincElement {
 
   @property({attribute: 'pad-y', type: Boolean}) padY: boolean;
 
+  // Column classes and stack ordering are written onto our children, so a re-render is needed
+  // whenever they change. Registered on the host and on each [stack-split] column, rather than
+  // the whole subtree, to avoid reacting to unrelated content updates deeper in a column.
+  private readonly childObserver: MutationObserver = new MutationObserver(() => this.requestUpdate());
+
+  connectedCallback() {
+    super.connectedCallback();
+    this.childObserver.observe(this, {childList: true});
+  }
+
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    this.childObserver.disconnect();
+  }
+
+  /**
+   * Reads the `stack-order` attribute of an element, returning null when it does not declare one.
+   */
+  private stackOrder(element: Element): number | null {
+    const raw = element.getAttribute('stack-order');
+    if (raw === null) return null;
+
+    const keyword = raw.trim().toLowerCase();
+    if (keyword in STACK_ORDER_KEYWORDS) return STACK_ORDER_KEYWORDS[keyword];
+
+    const order = parseInt(keyword, 10);
+    return isNaN(order) ? null : order;
+  }
+
+  /**
+   * Applies the declared stack order to an element. `--zn-stacked` is 0 until the container
+   * query in our stylesheet flips it to 1, so ordering only kicks in once stacked.
+   */
+  private applyStackOrder(element: HTMLElement, promoted: boolean): number | null {
+    const order = this.stackOrder(element);
+    element.style.order = order === null ? '' : `calc(var(--zn-stacked, 0) * ${order})`;
+
+    // Children of a [stack-split] column become columns themselves when stacked, at which point
+    // they need a basis to fill the row with. --zn-stack-basis is only set while stacked.
+    if (promoted) {
+      element.style.flexBasis = 'var(--zn-stack-basis, auto)';
+    }
+
+    return order;
+  }
+
   render() {
     const layout: number[] = this.layout.split(/[\s,]+/).map((a) => parseInt(a)).filter((item) => !!item);
 
@@ -58,6 +123,8 @@ export default class ZnCols extends ZincElement {
     const colsPerRow = layout.length;
     const lastRowStart = children.length - (children.length % colsPerRow || colsPerRow);
 
+    let stacks = false;
+
     children.forEach((element, index) => {
       const classes = element.className.split(' ').filter((c) => !c.startsWith(prefix));
       element.className = classes.join(' ');
@@ -71,8 +138,20 @@ export default class ZnCols extends ZincElement {
       } else {
         element.style.overflow = '';
       }
+
+      stacks = this.applyStackOrder(element, false) !== null || stacks;
+
+      if(element.hasAttribute('stack-split')) {
+        stacks = true;
+        this.childObserver.observe(element, {childList: true});
+        Array.from(element.children).forEach((child) => this.applyStackOrder(child as HTMLElement, true));
+      }
     });
 
+    if(stacks && !this.stackAt) {
+      this.stackAt = DEFAULT_STACK_AT;
+    }
+
     return html`
       <div part="base" class="${classMap({
         'cols': true,

package/src/components/cols/cols.scss

@@ -87,6 +87,14 @@
     border-bottom: 1px solid rgb(var(--zn-border-color)) !important;
   }
 
+  // Children marked with [stack-split] act as a single column while the cols are
+  // side by side, and dissolve into individual columns once stacked (see below).
+  ::slotted([stack-split]) {
+    display: flex;
+    flex-direction: column;
+    gap: var(--zn-gap);
+  }
+
   &--pad {
     padding: var(--zn-spacing-2x-small);
   }
@@ -99,3 +107,40 @@
     padding-block: var(--zn-spacing-2x-small);
   }
 }
+
+//
+// Responsive stacking
+//
+// `stack-at` names the container width the cols collapse to a single column below.
+// While stacked, `--zn-stacked` flips to 1 so the per-child `order: calc(var(--zn-stacked) * n)`
+// written by the component only takes effect in the stacked state, and `--zn-stack-basis`
+// gives promoted [stack-split] children something to size against.
+//
+// `:host()` is only in the selector to out-specify the `.zn-col-#{$i}` min-width rules above.
+//
+$stack-sizes: (sm, smp, ph, md, lg, hd, '3k', '4k');
+
+@each $size in $stack-sizes {
+  :host([stack-at="#{$size}"]) {
+    @include wc.container-query(null, $size) {
+      .cols ::slotted(*) {
+        --zn-stacked: 1;
+        --zn-stack-basis: 100%;
+
+        flex-basis: 100%;
+        min-width: 100%;
+        max-width: 100%;
+      }
+
+      // Hand this column's children over to the cols so each can be ordered individually
+      .cols ::slotted([stack-split]) {
+        display: contents;
+      }
+
+      // Vertical dividers make no sense once the columns are on top of each other
+      .cols--divide ::slotted(*:not(:last-child)):after {
+        display: none;
+      }
+    }
+  }
+}

package/src/components/cols/cols.test.ts

@@ -1,10 +1,138 @@
 import '../../../dist/zn.min.js';
-import { expect, fixture, html } from '@open-wc/testing';
+import {aTimeout, expect, fixture} from '@open-wc/testing';
+import type {LitElement} from 'lit';
 
-describe('<zn-columns>', () => {
+/** Reads the flex order the browser actually resolved for a light DOM child */
+const orderOf = (el: Element | null) => getComputedStyle(el!).order;
+
+const cols = async (markup: string) => {
+  const el = await fixture<LitElement>(markup);
+  await el.updateComplete;
+  return el;
+};
+
+describe('<zn-cols>', () => {
   it('should render a component', async () => {
-    const el = await fixture(html` <zn-columns></zn-columns> `);
+    const el = await fixture('<zn-cols></zn-cols>');
 
     expect(el).to.exist;
   });
+
+  it('should assign column classes from the layout pattern', async () => {
+    const el = await cols(`
+      <zn-cols layout="2,1">
+        <div id="main"></div>
+        <div id="side"></div>
+        <div id="wrapped"></div>
+      </zn-cols>`);
+
+    expect(el.querySelector('#main')).to.have.class('zn-col-2');
+    expect(el.querySelector('#side')).to.have.class('zn-col-1');
+    expect(el.querySelector('#wrapped')).to.have.class('zn-col-2');
+  });
+
+  describe('stacking', () => {
+    it('should not stack unless asked to', async () => {
+      const el = await cols(`
+        <zn-cols layout="2,1">
+          <div></div>
+          <div></div>
+        </zn-cols>`);
+
+      expect(el.getAttribute('stack-at')).to.equal('');
+    });
+
+    it('should default stack-at when a child declares a stack order', async () => {
+      const el = await cols(`
+        <zn-cols layout="2,1">
+          <div></div>
+          <div stack-order="first"></div>
+        </zn-cols>`);
+      await el.updateComplete;
+
+      expect(el.getAttribute('stack-at')).to.equal('lg');
+    });
+
+    it('should keep an explicit stack-at', async () => {
+      const el = await cols(`
+        <zn-cols layout="2,1" stack-at="md">
+          <div></div>
+          <div stack-order="first"></div>
+        </zn-cols>`);
+      await el.updateComplete;
+
+      expect(el.getAttribute('stack-at')).to.equal('md');
+    });
+
+    it('should only apply the stack order once stacked', async () => {
+      const el = await cols(`
+        <zn-cols layout="2,1" stack-at="md" style="width: 900px">
+          <div id="main"></div>
+          <div id="side" stack-order="first"></div>
+        </zn-cols>`);
+
+      expect(orderOf(el.querySelector('#side'))).to.equal('0');
+
+      el.style.width = '500px';
+      await aTimeout(50);
+
+      expect(orderOf(el.querySelector('#side'))).to.equal('-1');
+      expect(orderOf(el.querySelector('#main'))).to.equal('0');
+    });
+
+    it('should accept keywords and integers as a stack order', async () => {
+      const el = await cols(`
+        <zn-cols layout="2,1" stack-at="md" style="width: 500px">
+          <div id="a" stack-order="high"></div>
+          <div id="b" stack-order="low"></div>
+          <div id="c" stack-order="3"></div>
+          <div id="d" stack-order="nonsense"></div>
+        </zn-cols>`);
+
+      expect(orderOf(el.querySelector('#a'))).to.equal('-1');
+      expect(orderOf(el.querySelector('#b'))).to.equal('1');
+      expect(orderOf(el.querySelector('#c'))).to.equal('3');
+      expect(orderOf(el.querySelector('#d'))).to.equal('0');
+    });
+
+    it('should split a column into individually ordered children once stacked', async () => {
+      const el = await cols(`
+        <zn-cols layout="2,1" stack-at="md" style="width: 900px">
+          <div id="main" style="height: 100px"></div>
+          <div id="side" stack-split>
+            <div id="usage" stack-order="high" style="height: 20px"></div>
+            <div id="tutorials" stack-order="low" style="height: 20px"></div>
+          </div>
+        </zn-cols>`);
+
+      // Side by side, the split column is a single column holding both of its children
+      expect(getComputedStyle(el.querySelector('#side')!).display).to.equal('flex');
+      expect(orderOf(el.querySelector('#usage'))).to.equal('0');
+
+      el.style.width = '500px';
+      await aTimeout(50);
+
+      // Stacked, the column dissolves so each of its children becomes a column of its own
+      expect(getComputedStyle(el.querySelector('#side')!).display).to.equal('contents');
+      expect(orderOf(el.querySelector('#usage'))).to.equal('-1');
+      expect(orderOf(el.querySelector('#tutorials'))).to.equal('1');
+
+      const top = (selector: string) => el.querySelector(selector)!.getBoundingClientRect().top;
+      expect(top('#usage')).to.be.lessThan(top('#main'));
+      expect(top('#tutorials')).to.be.greaterThan(top('#main'));
+    });
+
+    it('should order children added after the initial render', async () => {
+      const el = await cols(`
+        <zn-cols layout="2,1" stack-at="md" style="width: 500px">
+          <div id="main"></div>
+          <div id="side" stack-split></div>
+        </zn-cols>`);
+
+      el.querySelector('#side')!.innerHTML = '<div id="usage" stack-order="high"></div>';
+      await aTimeout(50);
+
+      expect(orderOf(el.querySelector('#usage'))).to.equal('-1');
+    });
+  });
 });

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

@@ -33,11 +33,17 @@ export default class ZnTranslations extends ZincElement implements ZincFormContr
   };
 
   private readonly formControlController: FormControlController = new FormControlController(this);
-  private readonly hasSlotController = new HasSlotController(this, 'label', 'expand');
+  private readonly hasSlotController = new HasSlotController(this, 'label', 'expand', 'help-text');
 
   @property() name = '';
   @property() value = '{"en":""}';
   @property() label: string = '';
+
+  /**
+   * Text shown below the field, describing how to fill it in. Applies to every language. If you need HTML, use the
+   * `help-text` slot instead.
+   */
+  @property({attribute: 'help-text'}) helpText: string = '';
   @property({type: Boolean, reflect: true}) disabled = false;
   @property({type: Boolean, reflect: true}) required = false;
   @property({type: Boolean, reflect: true}) flush = false;
@@ -356,6 +362,8 @@ export default class ZnTranslations extends ZincElement implements ZincFormContr
     const hasLabelSlot = this.hasSlotController.test('label');
     const hasLabel = this.label ? true : hasLabelSlot;
     const hasExpandSlot = this.hasSlotController.test('expand');
+    const hasHelpTextSlot = this.hasSlotController.test('help-text');
+    const hasHelpText = this.helpText ? true : hasHelpTextSlot;
     const hasMultipleLanguages = Object.keys(this.languages).length > 1;
     const showActions = !this.grouped && (hasMultipleLanguages || hasExpandSlot);
 
@@ -368,6 +376,7 @@ export default class ZnTranslations extends ZincElement implements ZincFormContr
              'form-control': true,
              'form-control--medium': true,
              'form-control--has-label': hasLabel,
+             'form-control--has-help-text': hasHelpText,
            })}"
            @keydown="${this.handleKeyDown}">
         <div class="translations__header">
@@ -443,6 +452,12 @@ export default class ZnTranslations extends ZincElement implements ZincFormContr
             ></zn-inline-edit>
           `)}
         </div>
+
+        ${hasHelpText ? html`
+          <div part="form-control-help-text" class="form-control__help-text" aria-hidden="false">
+            <slot name="help-text">${this.helpText}</slot>
+          </div>
+        ` : nothing}
       </div>
     `;
   }

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

@@ -50,6 +50,48 @@ describe('<zn-translations>', () => {
     await expect(JSON.parse(el.value)).to.deep.equal({'en': 'Hello World'});
   });
 
+  describe('help text', () => {
+    function helpTextOf(el: ZnTranslations) {
+      return el.shadowRoot!.querySelector<HTMLElement>('[part="form-control-help-text"]');
+    }
+
+    it('is not rendered when unset', async () => {
+      const el = await fixture<ZnTranslations>(html`<zn-translations></zn-translations>`);
+      await el.updateComplete;
+
+      expect(helpTextOf(el)).to.not.exist;
+    });
+
+    it('renders the help-text attribute below the field', async () => {
+      const el = await fixture<ZnTranslations>(html`
+        <zn-translations help-text="Type / to insert a replacement"></zn-translations>`);
+      await el.updateComplete;
+
+      expect(helpTextOf(el)?.textContent?.trim()).to.equal('Type / to insert a replacement');
+    });
+
+    it('renders the help-text slot', async () => {
+      const el = await fixture<ZnTranslations>(html`
+        <zn-translations>
+          <div slot="help-text">Type <strong>/</strong> to insert</div>
+        </zn-translations>`);
+      await el.updateComplete;
+
+      expect(helpTextOf(el), 'a slotted help text should still render the wrapper').to.exist;
+    });
+
+    it('shows the same help text after switching language', async () => {
+      const el = await fixture<ZnTranslations>(html`
+        <zn-translations help-text="Type / to insert a replacement"></zn-translations>`);
+      el.languages = {'en': 'EN', 'fr': 'FR'};
+      el.values = {'en': '', 'fr': ''};
+      el.setActiveLanguage('fr');
+      await el.updateComplete;
+
+      expect(helpTextOf(el)?.textContent?.trim()).to.equal('Type / to insert a replacement');
+    });
+  });
+
   describe('slash menu', () => {
     /** Puts the active language's field into edit mode, the way clicking it does. */
     async function textareaOf(el: ZnTranslations) {