@kubex/zinc 2.0.3 → 2.0.4

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

@@ -39,6 +39,17 @@ Use the `with-reset` attribute to add a button that resets the form's fields.
 </form>
 ```
 
+### Hide Until Changed
+
+Use the `hide-until-changed` attribute to keep the row hidden until a field in the form changes. It hides again once the form is back to its original values — undone by hand, reset, or saved.
+
+```html:preview
+<form>
+  <zn-input name="title" label="Title" value="Edit me"></zn-input>
+  <zn-form-actions hide-until-changed with-reset></zn-form-actions>
+</form>
+```
+
 ### Custom Text and Icons
 
 Each button's text and icon can be overridden with `submit-text` / `submit-icon`, `cancel-text` / `cancel-icon` and `reset-text` / `reset-icon`.

package/package.json

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

package/scss/_global-spacing.scss

@@ -89,6 +89,13 @@ zn-sp[divide] > zn-form-group ~ zn-form-group {
   border-top: 0;
 }
 
+// Divided rows of fields keep the plain field spacing, half each side of the line, where divided sections keep the
+// full gap either side.
+zn-sp[divide]:has(> zn-toggle, > zn-input, > zn-select, > zn-checkbox, > zn-textarea, > zn-datepicker,
+  > zn-radio-group, > zn-checkbox-group) {
+  --zn-sp-gap: calc(var(--zn-form-row-gap, var(--zn-spacing-medium)) / 2);
+}
+
 
 .form-spacing > * {
   grid-column: span 6 / span 6;

package/scss/_root.scss

@@ -14,6 +14,7 @@
   --zn-page-closer-size: 36px;
   --zn-page-closer-gap: var(--zn-spacing-x-small);
   --zn-gutter: 2px;
+  // zn-page centres its content box, so containers inside it start at its left edge, in line with the header
   --zn-default-margin: 0 auto 0 0;
   --zn-icon-size: 20px;
   --zn-button-gutter: 2px;
@@ -75,11 +76,6 @@
   }
 }
 
-@media (min-width: 2500px) {
-  :root {
-    --zn-default-margin: 0 auto;
-  }
-}
 
 
 :root {

package/src/components/form-actions/form-actions.component.ts

@@ -1,4 +1,5 @@
 import {type CSSResultGroup, html, unsafeCSS} from 'lit';
+import {formCollections} from '../../internal/form';
 import {idSelector} from "../../utilities/query";
 import {property, state} from 'lit/decorators.js';
 import ZincElement from '../../internal/zinc-element';
@@ -21,10 +22,20 @@ import styles from './form-actions.scss';
  * number can sit on either side. Write them in the order they should be read — the sides are set by CSS ordering, so
  * markup order is what a keyboard follows.
  *
+ * @csspart base - The row holding the actions.
  * @csspart cancel-button - The cancel button.
  * @csspart reset-button - The reset button.
  * @csspart submit-button - The submit button.
  */
+const CHANGE_EVENTS = ['input', 'change', 'zn-input', 'zn-change'];
+
+// An empty multi-select reports '', [''] or [] depending on whether it was loaded, reset or cleared by hand
+const normaliseValue = (value: unknown): unknown =>
+  typeof value === 'string' || Array.isArray(value)
+    ? (Array.isArray(value) ? value : [value]).filter(v => v !== '')
+    : value;
+const INTERACTION_EVENTS = ['pointerdown', 'keydown'];
+
 export default class ZnFormActions extends ZincElement {
   static styles: CSSResultGroup = unsafeCSS(styles);
   static dependencies = {
@@ -64,9 +75,18 @@ export default class ZnFormActions extends ZincElement {
    */
   @property({attribute: 'loading-on-submit', type: Boolean}) loadingOnSubmit = false;
 
+  /**
+   * Hides the row until the form's values differ from when it loaded or was last saved, and hides it again once
+   * they match.
+   */
+  @property({attribute: 'hide-until-changed', type: Boolean, reflect: true}) hideUntilChanged = false;
+
   @state() private submitting = false;
 
   private watchedForm: HTMLFormElement | null = null;
+  private changeForm: HTMLFormElement | null = null;
+  private baseline = '';
+  private interacted = false;
 
   connectedCallback() {
     super.connectedCallback();
@@ -76,6 +96,17 @@ export default class ZnFormActions extends ZincElement {
       this.watchedForm?.addEventListener('requested', this.handleRequested);
       ['complete', 'error', 'cancelled'].forEach(e => this.watchedForm?.addEventListener(e, this.handleDone));
     }
+
+    this.changeForm = this.hideUntilChanged ? this.getForm() : null;
+    if (this.changeForm) {
+      CHANGE_EVENTS.forEach(e => this.changeForm!.addEventListener(e, this.checkForChanges));
+      INTERACTION_EVENTS.forEach(e => this.changeForm!.addEventListener(e, this.refreshBaseline, {capture: true}));
+      this.changeForm.addEventListener('reset', this.handleFormReset);
+      this.changeForm.addEventListener('complete', this.markSaved);
+      this.toggleAttribute('data-unchanged', true);
+      // Controls later in the form may not have upgraded or set their values yet
+      requestAnimationFrame(this.markSaved);
+    }
   }
 
   disconnectedCallback() {
@@ -83,9 +114,74 @@ export default class ZnFormActions extends ZincElement {
     this.watchedForm?.removeEventListener('requested', this.handleRequested);
     ['complete', 'error', 'cancelled'].forEach(e => this.watchedForm?.removeEventListener(e, this.handleDone));
     this.watchedForm = null;
+
+    CHANGE_EVENTS.forEach(e => this.changeForm?.removeEventListener(e, this.checkForChanges));
+    INTERACTION_EVENTS.forEach(e => this.changeForm?.removeEventListener(e, this.refreshBaseline, {capture: true}));
+    this.interacted = false;
+    this.changeForm?.removeEventListener('reset', this.handleFormReset);
+    this.changeForm?.removeEventListener('complete', this.markSaved);
+    this.changeForm = null;
     super.disconnectedCallback();
   }
 
+  /**
+   * The form's values, compared against the baseline. Read from the controls directly, since building FormData runs
+   * zinc controls' formdata handlers, which trim the value being typed.
+   */
+  private snapshot(): string {
+    const form = this.changeForm;
+    if (!form) return '';
+
+    const entries: unknown[] = [];
+    for (const el of Array.from(form.elements)) {
+      if (!(el instanceof HTMLInputElement || el instanceof HTMLSelectElement || el instanceof HTMLTextAreaElement)
+        || !el.name) continue;
+      if (el instanceof HTMLInputElement && (el.type === 'checkbox' || el.type === 'radio')) {
+        entries.push([el.name, el.value, el.checked]);
+      } else if (el instanceof HTMLInputElement && el.type === 'file') {
+        entries.push([el.name, Array.from(el.files ?? [], f => f.name)]);
+      } else if (el instanceof HTMLSelectElement) {
+        entries.push([el.name, Array.from(el.selectedOptions, o => o.value)]);
+      } else {
+        entries.push([el.name, el.value]);
+      }
+    }
+    formCollections.get(form)?.forEach(control => {
+      // Disabled controls still count: a conditional control disabling is a side effect of another change
+      if (!control.name) return;
+      // A toggle's value only appears once it's first clicked, so on/off controls compare by checked alone
+      const checked = (control as {checked?: boolean}).checked;
+      entries.push(typeof checked === 'boolean' ? [control.name, checked] : [control.name, normaliseValue(control.value)]);
+    });
+
+    return JSON.stringify(entries);
+  }
+
+  private checkForChanges = () => {
+    // Before the user touches the form, changes come from controls settling (options loading, select-first)
+    if (!this.interacted) {
+      this.baseline = this.snapshot();
+      return;
+    }
+    this.toggleAttribute('data-unchanged', this.snapshot() === this.baseline);
+  };
+
+  private markSaved = () => {
+    this.baseline = this.snapshot();
+    this.toggleAttribute('data-unchanged', true);
+  };
+
+  // Values set by code between edits (remote options, late data) aren't user changes, so re-read them while unchanged
+  private refreshBaseline = () => {
+    this.interacted = true;
+    if (this.hasAttribute('data-unchanged')) this.baseline = this.snapshot();
+  };
+
+  // Controls reset their values after the reset event
+  private handleFormReset = () => {
+    setTimeout(this.checkForChanges);
+  };
+
   // Only the original submit is blocked; the console re-dispatches it as a composed event
   private handleFormSubmit = (e: Event) => {
     if (this.submitting && !e.composed) {
@@ -127,19 +223,21 @@ export default class ZnFormActions extends ZincElement {
 
   render() {
     return html`
-      <slot></slot>
-      <span class="form-actions__spacer"></span>
-      ${this.withCancel ? html`
-        <zn-button part="cancel-button" panel-bg modal-closer icon="${this.cancelIcon}" @click="${this.handleCancel}">
-          ${this.cancelText}
-        </zn-button>` : ''}
-      ${this.withReset ? html`
-        <zn-button part="reset-button" panel-bg icon="${this.resetIcon}" @click="${this.handleReset}">
-          ${this.resetText}
-        </zn-button>` : ''}
-      <zn-button part="submit-button" color="primary" icon="${this.submitIcon}" @click="${this.handleSubmit}"
-                 ?loading=${this.submitting} ?disabled=${this.submitting} loading-text="${this.submitText}">
-        ${this.submitText}
-      </zn-button>`;
+      <div part="base" class="form-actions">
+        <slot></slot>
+        <span class="form-actions__spacer"></span>
+        ${this.withCancel ? html`
+          <zn-button part="cancel-button" panel-bg modal-closer icon="${this.cancelIcon}" @click="${this.handleCancel}">
+            ${this.cancelText}
+          </zn-button>` : ''}
+        ${this.withReset ? html`
+          <zn-button part="reset-button" panel-bg icon="${this.resetIcon}" @click="${this.handleReset}">
+            ${this.resetText}
+          </zn-button>` : ''}
+        <zn-button part="submit-button" color="primary" icon="${this.submitIcon}" @click="${this.handleSubmit}"
+                   ?loading=${this.submitting} ?disabled=${this.submitting} loading-text="${this.submitText}">
+          ${this.submitText}
+        </zn-button>
+      </div>`;
   }
 }

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

@@ -1,11 +1,22 @@
 @use "../../wc";
 
-// Keep in sync with the global .form-actions layout in scss/_global-spacing.scss.
+// One grid row, so hide-until-changed can collapse the height by animating the track between 1fr and 0fr.
 :host {
+  --form-actions-ease: var(--zn-ease-out, cubic-bezier(0.23, 1, 0.32, 1));
+  display: grid;
+  grid-template-rows: 1fr;
+  transition: grid-template-rows 200ms var(--form-actions-ease),
+  opacity 200ms var(--form-actions-ease),
+  display 200ms allow-discrete;
+}
+
+// Keep in sync with the global .form-actions layout in scss/_global-spacing.scss.
+.form-actions {
   display: flex;
   justify-content: flex-end;
   align-items: center;
   gap: var(--zn-form-actions-gap, var(--zn-spacing-small));
+  min-height: 0;
 }
 
 // The spacer, not an auto margin, is what splits the two sides: an auto margin on every left-hand action would open
@@ -24,3 +35,28 @@ zn-button {
 ::slotted([align='start']) {
   order: 0;
 }
+
+// display: none lands once the collapse finishes, dropping the parent's gap around the row as well
+:host([data-unchanged]) {
+  display: none;
+  grid-template-rows: 0fr;
+  opacity: 0;
+  transition-duration: var(--zn-transition-fast, 150ms);
+
+  .form-actions {
+    overflow: hidden;
+  }
+}
+
+@starting-style {
+  :host([hide-until-changed]:not([data-unchanged])) {
+    grid-template-rows: 0fr;
+    opacity: 0;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  :host {
+    transition-property: opacity, display;
+  }
+}

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

@@ -45,6 +45,143 @@ describe('<zn-form-actions>', () => {
     expect(submit.left).to.be.closeTo(cancel.right + 16, 1);
   });
 
+  it('shows only while the form differs from its loaded values', async () => {
+    const form = await fixture<HTMLFormElement>(html`
+      <form>
+        <input name="title" value="a">
+        <zn-form-actions hide-until-changed></zn-form-actions>
+      </form>
+    `);
+    const actions = form.querySelector('zn-form-actions')!;
+    const input = form.querySelector('input')!;
+    const visible = async () => {
+      await Promise.all(actions.getAnimations().map(animation => animation.finished));
+      return getComputedStyle(actions).display !== 'none';
+    };
+    const type = (value: string) => {
+      input.dispatchEvent(new Event('keydown', { bubbles: true }));
+      input.value = value;
+      input.dispatchEvent(new Event('input', { bubbles: true }));
+    };
+    await new Promise(requestAnimationFrame);
+
+    expect(await visible()).to.be.false;
+
+    type('b');
+    expect(await visible()).to.be.true;
+
+    type('a');
+    expect(await visible()).to.be.false;
+
+    type('b');
+    form.reset();
+    await new Promise(resolve => setTimeout(resolve));
+    expect(await visible()).to.be.false;
+  });
+
+  it('hides again when a toggle is switched back', async () => {
+    const form = await fixture<HTMLFormElement>(html`
+      <form>
+        <zn-toggle name="auto"></zn-toggle>
+        <zn-form-actions hide-until-changed></zn-form-actions>
+      </form>
+    `);
+    const actions = form.querySelector('zn-form-actions')!;
+    const toggle = form.querySelector('zn-toggle')!;
+    await new Promise(requestAnimationFrame);
+    const flip = async () => {
+      toggle.dispatchEvent(new Event('pointerdown', { bubbles: true }));
+      toggle.shadowRoot!.querySelector('input')!.click();
+      await (toggle as HTMLElement & { updateComplete: Promise<unknown> }).updateComplete;
+    };
+
+    await flip();
+    expect(actions.hasAttribute('data-unchanged')).to.be.false;
+
+    await flip();
+    expect(actions.hasAttribute('data-unchanged')).to.be.true;
+  });
+
+  it('hides again when an empty multi-select is changed then reset', async () => {
+    const form = await fixture<HTMLFormElement>(html`
+      <form>
+        <zn-select name="groups" multiple>
+          <zn-option value="a">A</zn-option>
+          <zn-option value="b">B</zn-option>
+        </zn-select>
+        <zn-form-actions hide-until-changed></zn-form-actions>
+      </form>
+    `);
+    const actions = form.querySelector('zn-form-actions')!;
+    const select = form.querySelector<HTMLElement & { value: string[] }>('zn-select')!;
+    await new Promise(requestAnimationFrame);
+
+    select.dispatchEvent(new Event('pointerdown', { bubbles: true }));
+    select.value = ['a'];
+    select.dispatchEvent(new Event('zn-change', { bubbles: true }));
+    expect(actions.hasAttribute('data-unchanged')).to.be.false;
+
+    form.reset();
+    await new Promise(resolve => setTimeout(resolve));
+    expect(actions.hasAttribute('data-unchanged')).to.be.true;
+  });
+
+  it('hides again when a reset re-enables a conditional select', async () => {
+    const form = await fixture<HTMLFormElement>(html`
+      <form>
+        <zn-select id="allowed" name="allowed" multiple value="" provider="conditional" conditional="blocked">
+          <zn-option value="a">A</zn-option>
+        </zn-select>
+        <zn-select id="blocked" name="blocked" multiple value="" provider="conditional" conditional="allowed">
+          <zn-option value="a">A</zn-option>
+        </zn-select>
+        <zn-form-actions hide-until-changed></zn-form-actions>
+      </form>
+    `);
+    const actions = form.querySelector('zn-form-actions')!;
+    const blocked = form.querySelector<HTMLElement & { value: string[] }>('#blocked')!;
+    await new Promise(requestAnimationFrame);
+
+    blocked.dispatchEvent(new Event('pointerdown', { bubbles: true }));
+    blocked.value = ['a'];
+    blocked.dispatchEvent(new Event('zn-change', { bubbles: true }));
+    expect(actions.hasAttribute('data-unchanged')).to.be.false;
+
+    form.reset();
+    await new Promise(resolve => setTimeout(resolve, 10));
+    expect(actions.hasAttribute('data-unchanged')).to.be.true;
+  });
+
+  it('treats changes before any interaction as the starting values', async () => {
+    const form = await fixture<HTMLFormElement>(html`
+      <form>
+        <input name="type" value="">
+        <zn-form-actions hide-until-changed></zn-form-actions>
+      </form>
+    `);
+    const actions = form.querySelector('zn-form-actions')!;
+    const input = form.querySelector('input')!;
+    await new Promise(requestAnimationFrame);
+
+    // As zn-select does when its options load or select-first picks one
+    input.value = 'team';
+    input.dispatchEvent(new Event('change', { bubbles: true }));
+
+    expect(actions.hasAttribute('data-unchanged')).to.be.true;
+  });
+
+  it('stays visible in an unchanged form without hide-until-changed', async () => {
+    const form = await fixture<HTMLFormElement>(html`
+      <form>
+        <input name="title" value="a">
+        <zn-form-actions></zn-form-actions>
+      </form>
+    `);
+    await new Promise(requestAnimationFrame);
+
+    expect(getComputedStyle(form.querySelector('zn-form-actions')!).display).to.not.equal('none');
+  });
+
   it('should close a containing dialog when the cancel button is clicked', async () => {
     const dialog = await fixture<HTMLElement & { open: boolean }>(html`
       <zn-dialog open label="Test">

package/src/components/input/input.scss

@@ -162,6 +162,29 @@ input[type='text'].input__control[data-color-input] {
   }
 }
 
+// The same gap right of a suffix as above and below one 24px tall (an icon or copy button). Built-in controls such as
+// the clear button and stepper keep their own spacing.
+.input__suffix ::slotted(*) {
+  margin-inline-end: max(2px, calc((var(--input-height) - var(--zn-input-border-width) * 2 - 24px) / 2));
+}
+
+// Slotted buttons are held to the small button height, shrunk to fit smaller inputs, with the same gap all round.
+// Read from the density token: redefining --zn-button-height-small from itself would be a cycle.
+.input__suffix ::slotted(zn-button) {
+  --input-suffix-button-height: min(var(--zn-density-control-height-sm, 28px), calc(var(--input-height) - var(--zn-input-border-width) * 2 - 4px));
+  --zn-button-height: var(--input-suffix-button-height);
+  --zn-button-height-small: var(--input-suffix-button-height);
+  margin-inline-end: calc((var(--input-height) - var(--zn-input-border-width) * 2 - var(--input-suffix-button-height)) / 2);
+}
+
+.input__suffix ::slotted(zn-checkbox) {
+  margin-inline-end: 0;
+}
+
+.input__suffix-default {
+  margin-inline-end: var(--zn-spacing-small);
+}
+
 .input__prefix ::slotted(zn-icon),
 .input__suffix ::slotted(zn-icon) {
   --icon-size: var(--zn-font-size-medium);
@@ -174,6 +197,7 @@ input[type='text'].input__control[data-color-input] {
  */
 
 .input--x-small {
+  --input-height: var(--zn-input-height-x-small);
   border-radius: var(--zn-input-border-radius-x-small);
   font-size: var(--zn-input-font-size-small);
   height: var(--zn-input-height-x-small);
@@ -194,20 +218,14 @@ input[type='text'].input__control[data-color-input] {
   margin-inline-start: var(--zn-spacing-x-small);
 }
 
-.input--x-small .input__suffix ::slotted(*),
-.input__suffix-default {
-  margin-inline-end: var(--zn-input-spacing-x-small);
-}
-
-.input--x-small .input__suffix ::slotted(zn-button),
 .input--x-small .input__prefix ::slotted(zn-button),
-.input--x-small .input__suffix ::slotted(zn-checkbox),
-.input--x-small .input__prefix ::slotted(zn-checkbox), {
+.input--x-small .input__prefix ::slotted(zn-checkbox) {
   margin-inline-end: 0;
   margin-inline-start: 0;
 }
 
 .input--small {
+  --input-height: var(--zn-input-height-small);
   border-radius: var(--zn-input-border-radius-small);
   font-size: var(--zn-input-font-size-small);
   height: var(--zn-input-height-small);
@@ -228,20 +246,14 @@ input[type='text'].input__control[data-color-input] {
   margin-inline-start: var(--zn-input-spacing-small);
 }
 
-.input--small .input__suffix ::slotted(*),
-.input__suffix-default {
-  margin-inline-end: var(--zn-input-spacing-small);
-}
-
-.input--small .input__suffix ::slotted(zn-button),
 .input--small .input__prefix ::slotted(zn-button),
-.input--small .input__suffix ::slotted(zn-checkbox),
 .input--small .input__prefix ::slotted(zn-checkbox) {
   margin-inline-end: 0;
   margin-inline-start: 0;
 }
 
 .input--medium {
+  --input-height: var(--zn-input-height-medium);
   border-radius: var(--zn-input-border-radius-medium);
   font-size: var(--zn-input-font-size-medium);
   height: var(--zn-input-height-medium);
@@ -262,34 +274,23 @@ input[type='text'].input__control[data-color-input] {
   margin-inline-start: var(--zn-spacing-small);
 }
 
-.input--medium .input__suffix ::slotted(*),
-.input__suffix-default {
-  margin-inline-end: var(--zn-spacing-small);
-}
-
-.input--medium .input__suffix ::slotted(zn-button),
 .input--medium .input__prefix ::slotted(zn-button),
-.input--medium .input__suffix ::slotted(zn-checkbox),
 .input--medium .input__prefix ::slotted(zn-checkbox) {
   margin-inline-end: 0;
   margin-inline-start: 0;
 }
 
-.input__suffix ::slotted(zn-button),
 .input__prefix ::slotted(zn-button) {
   --zn-button-border-color: rgb(var(--zn-color-border));
   --zn-button-border-width: 0;
 }
 
-.input__suffix ::slotted(zn-button) {
-  --zn-button-border-left-width: 1px;
-}
-
 .input__prefix ::slotted(zn-button) {
   --zn-button-border-right-width: 1px;
 }
 
 .input--large {
+  --input-height: var(--zn-input-height-large);
   border-radius: var(--zn-input-border-radius-large);
   font-size: var(--zn-input-font-size-large);
   height: var(--zn-input-height-large);
@@ -305,9 +306,7 @@ input[type='text'].input__control[data-color-input] {
   width: calc(1em + var(--zn-input-spacing-large) * 2);
 }
 
-.input--large .input__suffix ::slotted(zn-button),
 .input--large .input__prefix ::slotted(zn-button),
-.input--large .input__suffix ::slotted(zn-checkbox),
 .input--large .input__prefix ::slotted(zn-checkbox) {
   margin-inline-end: 0;
   margin-inline-start: 0;