@kubex/zinc 1.1.82 → 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubex/zinc",
-  "version": "1.1.82",
+  "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');
+    });
+  });
 });