@kubex/zinc 1.1.81 → 1.1.82

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.82",
   "description": "A collection of web components for building web applications based off of @shoelace-style/Shoelace",
   "keywords": [
     "web components",

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) {