@kubex/zinc 1.1.58 → 1.1.60

package/docs/pages/components/input.md

@@ -416,6 +416,36 @@ Form navigation works with all Zinc form controls including selects, radios, che
 **Note:** While you can navigate TO textareas and search inputs using Enter, pressing Enter while inside these controls uses the Enter key for their own functionality (new lines and search triggers, respectively). Use Tab to navigate away from these controls.
 :::
 
+### Trigger Submit
+
+Add the `trigger-submit` attribute to make pressing Enter in the input always submit the surrounding form. Inputs already submit on Enter by default, so this is only needed on forms using `data-enter-navigation`, where Enter would otherwise move focus to the next field.
+
+```html:preview
+<form class="trigger-submit-form" data-enter-navigation>
+  <zn-input name="firstName" label="First Name" required></zn-input>
+  <br />
+  <zn-input name="search" label="Quick Search (Enter submits)" trigger-submit></zn-input>
+  <br />
+  <zn-button type="submit" variant="primary">Submit</zn-button>
+</form>
+
+<script type="module">
+  const form = document.querySelector('.trigger-submit-form');
+
+  await Promise.all([
+    customElements.whenDefined('zn-button'),
+    customElements.whenDefined('zn-input')
+  ]).then(() => {
+    form.addEventListener('submit', (e) => {
+      e.preventDefault();
+      const formData = new FormData(form);
+      const data = Object.fromEntries(formData);
+      alert('Form submitted!\n\n' + JSON.stringify(data, null, 2));
+    });
+  });
+</script>
+```
+
 ### Customizing Label Position
 
 Use [CSS parts](#css-parts) to customize the way form controls are drawn. This example uses CSS grid to position the

package/docs/pages/components/toggle.md

@@ -62,6 +62,68 @@ Use the `label` attribute to add a form control label above the toggle.
 <zn-toggle label="User Preferences">Enable email notifications</zn-toggle>
 ```
 
+### Description
+
+Use the `description` attribute to add a description under the label. If you need to display HTML, use the `description` slot instead.
+
+```html:preview
+<zn-toggle label="Email notifications" description="Receive an email whenever someone mentions you."></zn-toggle>
+```
+
+The description stays under the label at every `label-position`, and can be combined with `help-text`, which always appears below the toggle.
+
+```html:preview
+<zn-toggle
+  label="Top label (default)"
+  description="Receive an email whenever someone mentions you."
+  help-text="You can change this at any time"></zn-toggle>
+<br />
+<zn-toggle
+  label="Left label"
+  label-position="left"
+  description="Receive an email whenever someone mentions you."
+  help-text="You can change this at any time"></zn-toggle>
+<br />
+<zn-toggle
+  label="Right label"
+  label-position="right"
+  description="Receive an email whenever someone mentions you."
+  help-text="You can change this at any time"></zn-toggle>
+```
+
+### Label Position
+
+Use the `label-position` attribute to control where the label sits relative to the toggle. Available positions are `top` (default), `left`, and `right`.
+
+With `left`, the label sits at the start of the row and the toggle is pushed to the far right — useful for settings lists. With `right`, the layout is mirrored.
+
+```html:preview
+<zn-toggle label="Top label (default)"></zn-toggle>
+<br />
+<zn-toggle label="Left label" label-position="left"></zn-toggle>
+<br />
+<zn-toggle label="Right label" label-position="right"></zn-toggle>
+```
+
+Combine `label-position` with the `inline` attribute to keep the label and toggle adjacent instead of spread across the full width.
+
+```html:preview
+<zn-toggle label="Inline left" label-position="left" inline></zn-toggle>
+<br />
+<zn-toggle label="Inline right" label-position="right" inline></zn-toggle>
+```
+
+A settings list using `label-position="left"`:
+
+```html:preview
+<div style="max-width: 320px;">
+  <zn-toggle label="Apple" label-position="left"></zn-toggle>
+  <zn-toggle label="Windows" label-position="left"></zn-toggle>
+  <zn-toggle label="Android" label-position="left"></zn-toggle>
+  <zn-toggle label="Blackberry" label-position="left" checked></zn-toggle>
+</div>
+```
+
 ### On/Off Text with Tooltip
 
 Use the `on-text` and `off-text` attributes to display tooltips that show when the toggle is in the on or off state. This provides additional context for the toggle's current state.

package/package.json

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

package/src/components/input/input.component.ts

@@ -212,6 +212,12 @@ export default class ZnInput extends ZincElement implements ZincFormControl {
    */
   @property() inputmode: 'none' | 'text' | 'decimal' | 'numeric' | 'tel' | 'search' | 'email' | 'url';
 
+  /**
+   * When enabled, pressing enter will always submit the surrounding form, even when the form uses
+   * enter-navigation to move between fields.
+   */
+  @property({type: Boolean, attribute: 'trigger-submit'}) triggerSubmit = false;
+
   //
   // NOTE: We use an in-memory input for these getters/setters instead of the one in the template because the properties
   // can be set before the component is rendered.
@@ -561,9 +567,10 @@ export default class ZnInput extends ZincElement implements ZincFormControl {
       // When using a Input Method Editor (IME), pressing enter will cause the form to submit unexpectedly. One way
       // to check for this is to look at event.isComposing, which will be true when the IME is open.
       if (!event.defaultPrevented && !event.isComposing) {
-        // Check if form has navigation enabled - if so, let FormNavigationController handle it
+        // Check if form has navigation enabled - if so, let FormNavigationController handle it,
+        // unless trigger-submit is set which always submits on enter
         const form = this.formControlController.getForm();
-        if (form?.hasAttribute('enter-navigation') || form?.hasAttribute('data-enter-navigation')) {
+        if (!this.triggerSubmit && (form?.hasAttribute('enter-navigation') || form?.hasAttribute('data-enter-navigation'))) {
           return; // Let FormNavigationController handle it
         }
 

package/src/components/input/input.test.ts

@@ -42,6 +42,61 @@ describe('<zn-input>', () => {
     });
   });
 
+  describe('trigger-submit', () => {
+    const pressEnter = (el: ZnInput) => {
+      el.input.dispatchEvent(new KeyboardEvent('keydown', {
+        key: 'Enter',
+        bubbles: true,
+        composed: true,
+        cancelable: true
+      }));
+    };
+
+    it('submits an enter-navigation form on enter when trigger-submit is set', async () => {
+      const form = await fixture<HTMLFormElement>(html`
+        <form data-enter-navigation>
+          <zn-input name="a" trigger-submit></zn-input>
+          <zn-input name="b"></zn-input>
+        </form>
+      `);
+      const el = form.querySelector('zn-input')!;
+      await el.updateComplete;
+
+      let submitted = false;
+      form.addEventListener('submit', e => {
+        e.preventDefault();
+        submitted = true;
+      });
+
+      el.focus();
+      pressEnter(el);
+
+      expect(submitted).to.be.true;
+    });
+
+    it('does not submit an enter-navigation form on enter without trigger-submit', async () => {
+      const form = await fixture<HTMLFormElement>(html`
+        <form data-enter-navigation>
+          <zn-input name="a"></zn-input>
+          <zn-input name="b"></zn-input>
+        </form>
+      `);
+      const el = form.querySelector('zn-input')!;
+      await el.updateComplete;
+
+      let submitted = false;
+      form.addEventListener('submit', e => {
+        e.preventDefault();
+        submitted = true;
+      });
+
+      el.focus();
+      pressEnter(el);
+
+      expect(submitted).to.be.false;
+    });
+  });
+
   describe('persisted state', () => {
     const formStoreKey = 'input-test-form-state';
     const elementStoreKey = 'input-test-element-state';

package/src/components/toggle/toggle.component.ts

@@ -2,6 +2,7 @@ import { classMap } from "lit/directives/class-map.js";
 import { type CSSResultGroup, html, type PropertyValues, unsafeCSS } from 'lit';
 import { defaultValue } from "../../internal/default-value";
 import { FormControlController } from "../../internal/form";
+import { HasSlotController } from "../../internal/slot";
 import { ifDefined } from "lit/directives/if-defined.js";
 import { live } from "lit/directives/live.js";
 import { property, query, state } from 'lit/decorators.js';
@@ -20,15 +21,20 @@ import styles from './toggle.scss';
  * @event zn-input - Emitted when the toggle receives input.
  *
  * @slot - The toggle's label.
+ * @slot description - A description of the toggle's label. Alternatively, you can use the `description` attribute.
+ * @slot help-text - Text that describes how to use the toggle. Alternatively, you can use the `help-text` attribute.
  *
  * @csspart base - The component's base wrapper containing the toggle switch.
  * @csspart control - The toggle switch control (the circular button that slides).
+ * @csspart description - The container that wraps the toggle's description.
  *
  * @cssproperty --zn-toggle-margin - The margin around the toggle switch. Defaults to `8px 0`.
  */
 export default class ZnToggle extends ZincElement implements ZincFormControl {
   static styles: CSSResultGroup = unsafeCSS(styles);
 
+  private readonly hasSlotController = new HasSlotController(this, 'help-text', 'description');
+
   private readonly formControlController = new FormControlController(this, {
     value: (control: ZnToggle) => (control.checked ? control.value || 'on' : undefined),
     defaultValue: (control: ZnToggle) => control.defaultChecked,
@@ -69,6 +75,11 @@ export default class ZnToggle extends ZincElement implements ZincFormControl {
 
   @property() label: string = '';
 
+  /** The toggle's description, displayed under the label. If you need to display HTML, use the `description` slot instead. */
+  @property() description: string = '';
+
+  @property({ attribute: 'label-position', reflect: true }) labelPosition: 'top' | 'left' | 'right' = 'top';
+
   @property({ type: Boolean }) inline: boolean = false;
 
   get validity() {
@@ -167,6 +178,8 @@ export default class ZnToggle extends ZincElement implements ZincFormControl {
 
     const tooltipContent = this.checked ? this.onText : this.offText;
     const showTooltip = !!tooltipContent;
+    const hasHelpText = this.helpText ? true : this.hasSlotController.test('help-text');
+    const hasDescription = this.description ? true : this.hasSlotController.test('description');
 
     const toggle = html`
       <div class="switch__input-wrapper" part="base">
@@ -182,7 +195,7 @@ export default class ZnToggle extends ZincElement implements ZincFormControl {
           .required=${this.required}
           role="switch"
           aria-checked=${this.checked ? 'true' : 'false'}
-          aria-describedby="help-text"
+          aria-describedby="description help-text"
           @click=${this.handleClick}
           @input=${this.handleInput}
           @invalid=${this.handleInvalid}
@@ -195,22 +208,45 @@ export default class ZnToggle extends ZincElement implements ZincFormControl {
 
     return html`
       <div class="${classMap({
+        'form-control': true,
+        'form-control--small': this.size === 'small',
+        'form-control--medium': this.size === 'medium',
+        'form-control--large': this.size === 'large',
+        'form-control--has-help-text': hasHelpText,
         'switch__wrapper': true,
+        'switch__wrapper--has-description': hasDescription,
         'switch__wrapper--disabled': this.disabled,
         'switch__wrapper--has-focus': this.hasFocus,
         'switch__wrapper--small': this.size === 'small',
         'switch__wrapper--medium': this.size === 'medium',
         'switch__wrapper--large': this.size === 'large',
-        'switch__wrapper--inline': this.inline
+        'switch__wrapper--inline': this.inline,
+        'switch__wrapper--label-left': this.labelPosition === 'left',
+        'switch__wrapper--label-right': this.labelPosition === 'right'
       })}">
         <label>
-          ${this.label ? html`<p class="switch-label">${this.label}</p>` : ''}
+          ${this.label || hasDescription ? html`
+            <div class="switch__label-wrapper">
+              ${this.label ? html`<p class="switch-label">${this.label}</p>` : ''}
+              <div part="description"
+                   id="description"
+                   class="switch__description"
+                   aria-hidden=${hasDescription ? 'false' : 'true'}>
+                <slot name="description">${this.description}</slot>
+              </div>
+            </div>` : ''}
           ${!showTooltip ? html`
             ${toggle}` : html`
             <zn-tooltip content="${tooltipContent}">
               ${toggle}
             </zn-tooltip>`}
         </label>
+        <div part="form-control-help-text"
+             id="help-text"
+             class="form-control__help-text"
+             aria-hidden=${hasHelpText ? 'false' : 'true'}>
+          <slot name="help-text">${this.helpText}</slot>
+        </div>
       </div>`;
   }
 }

package/src/components/toggle/toggle.scss

@@ -1,11 +1,22 @@
 @use "../../wc";
+@use "../../form-control";
 
 :host {
   --zn-toggle-margin: 8px 0;
+  display: block;
 }
 
 .switch__wrapper {
-  display: inline-flex;
+  display: flex;
+  flex-direction: column;
+
+  label {
+    flex: 1;
+    display: flex;
+    flex-direction: column;
+    align-items: flex-start;
+    cursor: pointer;
+  }
 }
 
 .switch__input-wrapper {
@@ -47,7 +58,33 @@
 }
 
 .switch-label {
-  font-size: 90%;
+  margin: 0;
+  color: var(--zn-input-label-color);
+  font-size: var(--zn-input-label-font-size-medium);
+  font-weight: var(--zn-input-label-font-weight);
+  line-height: var(--zn-input-label-line-height);
+}
+
+.switch__wrapper--small .switch-label {
+  font-size: var(--zn-input-label-font-size-small);
+}
+
+.switch__description {
+  display: none;
+}
+
+.switch__wrapper--has-description .switch__description {
+  display: block;
+  color: var(--zn-input-help-text-color);
+  font-size: var(--zn-input-font-size-small);
+}
+
+.switch__wrapper--small .switch__description {
+  font-size: var(--zn-font-size-x-small);
+}
+
+.switch__wrapper--large .switch-label {
+  font-size: var(--zn-input-label-font-size-large);
 }
 
 .switch__control {
@@ -91,10 +128,32 @@
   }
 }
 
+// Label position
+.switch__wrapper--label-left label,
+.switch__wrapper--label-right label {
+  align-items: center;
+  justify-content: space-between;
+  gap: 8px;
+}
+
+.switch__wrapper--label-left label {
+  flex-direction: row;
+}
+
+.switch__wrapper--label-right label {
+  flex-direction: row-reverse;
+}
+
 // Support inline label
+:host([inline]) {
+  display: inline-block;
+}
+
 .switch__wrapper--inline label {
+  flex: none;
+  flex-direction: row;
   align-items: center;
-  display: flex;
+  justify-content: flex-start;
   gap: 8px;
 
   .switch__input {
@@ -102,3 +161,7 @@
     margin-inline-end: 1px;
   }
 }
+
+.switch__wrapper--inline.switch__wrapper--label-right label {
+  flex-direction: row-reverse;
+}

package/src/components/toggle/toggle.test.ts

@@ -7,4 +7,15 @@ describe('<zn-toggle>', () => {
 
     expect(el).to.exist;
   });
+
+  it('should render the description under the label', async () => {
+    const el = await fixture<HTMLElement>(html`
+      <zn-toggle label="Email notifications" description="Receive an email when mentioned."></zn-toggle> `);
+
+    const label = el.shadowRoot!.querySelector('.switch-label')!;
+    const description = el.shadowRoot!.querySelector('[part="description"]')!;
+
+    expect(description.textContent).to.include('Receive an email when mentioned.');
+    expect(label.nextElementSibling).to.equal(description);
+  });
 });

package/src/internal/form-navigation.ts

@@ -46,6 +46,11 @@ export class FormNavigationController {
         return;
       }
 
+      // Controls with trigger-submit handle submitting the form themselves
+      if (target.hasAttribute('trigger-submit')) {
+        return;
+      }
+
       // Check if we're in a group (radio-group or checkbox-group)
       const group = this.findParentGroup(target);
       if (group) {