@kubex/zinc 1.1.117 → 1.1.118

package/docs/pages/components/translation-group.md

@@ -6,13 +6,16 @@ layout: component
 ---
 
 The Translation Group component wraps multiple `zn-translations` components in a panel-styled container with a shared
-language select. The select sits at the top right of the header, opposite the caption. Closed, it carries how many
-languages are done as a `1/5` chip; open, each language is marked translated, partial or falling back to English.
-Choosing a language switches every child at once.
+language select. The fields sit in a [form group](/components/form-group), so the caption, help text and the select
+share its label column and the fields line up with every other form group around them. Closed, the select carries how
+many languages are done as a `1/5` chip; open, each language is marked translated, partial or falling back to English.
+Type to filter the list — by name or by language code, so `de` finds German. Choosing a language switches every child
+at once.
 
 ```html:preview
 <zn-translation-group
   label="Product Content"
+  help-text="Every field is translated one language at a time"
   languages='{"en":"English","fr":"French","de":"German"}'>
   <zn-translations
     label="Name"
@@ -40,14 +43,16 @@ A translation group with two translation inputs sharing one language select.
 </zn-translation-group>
 ```
 
-### With Label
+### Label and Help Text
 
-Use the `label` attribute to add a caption on the left of the header, opposite the language select. `language-label`
-sets the select's accessible name — it is not shown, since the caption names the section on screen.
+`label` names the section in the form group's label column, and `help-text` sits under it — the pair behave as they do
+on any other form group. The language select follows them, in the group's chip position. `language-label` sets the
+select's accessible name — it is not shown, since the caption names the section on screen.
 
 ```html:preview
 <zn-translation-group
   label="Page Translations"
+  help-text="Pick a language to edit every field in it"
   languages='{"en":"English","fr":"French","es":"Spanish"}'>
   <zn-translations label="Heading" name="heading"></zn-translations>
   <zn-translations label="Body" name="body"></zn-translations>
@@ -209,7 +214,8 @@ The group emits a `zn-language-change` event when the active language changes.
 
 | Property         | Type                     | Default            | Description                                       |
 |------------------|--------------------------|--------------------|---------------------------------------------------|
-| `label`          | `string`                 | `''`               | Caption displayed in the panel header             |
+| `label`          | `string`                 | `''`               | Names the section, in the form group's label column |
+| `help-text`      | `string`                 | `''`               | Sits under the label, above the language select   |
 | `language-label` | `string`                 | `'Edit Languages'` | The select's accessible name; not shown on screen |
 | `inline`         | `boolean`                | `false`            | Drops the panel border, background and padding    |
 | `languages`      | `Record<string, string>` | `{en: "EN"}`       | Object mapping language codes to display names    |
@@ -226,19 +232,15 @@ The group emits a `zn-language-change` event when the active language changes.
 | Slot      | Description                                                |
 |-----------|------------------------------------------------------------|
 | (default) | Place `<zn-translations>` elements here                    |
-| `label`   | Alternative to the `label` attribute for rich HTML content |
 | `actions` | Buttons for the bottom of the body; `align="start"` on a child moves it to the left |
 | `footer`  | Content displayed in the grey panel footer                |
 
-The header carries the caption and the language select alone; nothing else is slotted into it.
-
 ## CSS Parts
 
-| Part              | Description                                                     |
-|-------------------|-----------------------------------------------------------------|
-| `base`            | The outer panel wrapper                                         |
-| `header`          | The header area containing the caption and the language select  |
-| `language-field`  | The container holding the language select                       |
-| `language-select` | The select itself                                               |
-| `actions`         | The row of buttons at the bottom of the body                    |
-| `translations`    | The body container wrapping the slotted children                |
+| Part              | Description                                                          |
+|-------------------|----------------------------------------------------------------------|
+| `base`            | The outer panel wrapper                                              |
+| `form-group`      | The form group holding the caption, the language select and the fields |
+| `language-field`  | The container holding the language select, in the group's chip slot   |
+| `language-select` | The select itself                                                    |
+| `actions`         | The row of buttons at the bottom of the body                         |

package/docs/pages/components/translations.md

@@ -128,8 +128,9 @@ Add `inline-edit` to read the translation as text until it is clicked, through
 
 ### Many Languages
 
-Each language becomes an option labelled `Name (CODE)` — or the code alone where the configured name already is the
-code. The select takes any number of them, and its listbox scrolls once the list is longer than the space below it.
+Each language becomes an option labelled with its configured name — or its code, where `languages` does not name it.
+The select takes any number of them, and its listbox scrolls once the list is longer than the space below it. Type to
+filter the list: matching runs over the code as well as the name, so `de` finds German.
 
 ```html:preview
 <zn-translations

package/package.json

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

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

@@ -47,6 +47,7 @@ export default class ZnFormGroup extends ZincElement {
 
   /** The scroller the label is tracked against by hand; null while native sticky is enough. */
   private tracked: HTMLElement | null = null;
+  private stickyTop: number = 0;
   private frame: number = 0;
   private rebind: boolean = false;
   private offset: number = 0;
@@ -103,9 +104,18 @@ export default class ZnFormGroup extends ZincElement {
     const column = this.labelColumn;
     if (!column) return;
 
+    column.style.top = '';
+    this.stickyTop = parseFloat(getComputedStyle(column).top) || 0;
+
     const anchor = this.nearestScrollContainer(column);
     const scroller = anchor ? this.scrollingAncestor(column) : null;
-    this.trackScroller(scroller === anchor ? null : scroller);
+    const anchored = !anchor || scroller === anchor;
+
+    this.trackScroller(anchored ? null : scroller);
+
+    // A `top` inset against a box that never scrolls has nothing to hold the label back from:
+    // it only pushes the label down the page, so drop it and let the transform do the work.
+    if (!anchored) column.style.top = '0px';
   }
 
   private trackScroller(scroller: HTMLElement | null) {
@@ -139,11 +149,10 @@ export default class ZnFormGroup extends ZincElement {
       const visibleTop = this.tracked === document.scrollingElement
         ? 0
         : this.tracked.getBoundingClientRect().top;
-      const stickyTop = parseFloat(getComputedStyle(column).top) || 0;
       const restingTop = column.getBoundingClientRect().top - this.offset;
       const travel = Math.max(0, fieldset.clientHeight - column.offsetHeight);
 
-      offset = Math.min(Math.max(visibleTop + stickyTop - restingTop, 0), travel);
+      offset = Math.min(Math.max(visibleTop + this.stickyTop - restingTop, 0), travel);
     }
 
     if (Math.round(offset) === Math.round(this.offset)) return;

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

@@ -77,6 +77,22 @@ describe('<zn-form-group>', () => {
       expect(position(narrow)).to.equal('static');
     });
 
+    it('leaves the label level with the inputs while nothing scrolls', async () => {
+      const el = await fixture<HTMLElement>(html`
+        <div style="width: 900px">
+          <zn-panel>
+            <zn-form-group label="Sticky"><zn-input label="Name"></zn-input></zn-form-group>
+          </zn-panel>
+        </div>`);
+      await new Promise(resolve => setTimeout(resolve, 100));
+
+      const root = el.querySelector('zn-form-group')!.shadowRoot!;
+      const label = root.querySelector('.form-control__text')!.getBoundingClientRect().top;
+      const inputs = root.querySelector('.form-control-input')!.getBoundingClientRect().top;
+
+      expect(label).to.be.closeTo(inputs, 2);
+    });
+
     it('holds the label in view when a panel sits between the form and the scroll container', async () => {
       const el = await fixture<HTMLElement>(html`
         <div style="max-height: 300px; overflow-y: auto">

package/src/components/translation-group/translation-group.component.ts

@@ -1,10 +1,9 @@
 import {classMap} from 'lit/directives/class-map.js';
 import {type CSSResultGroup, html, nothing, type PropertyValues, unsafeCSS} from 'lit';
 import {HasSlotController} from '../../internal/slot';
-import {ifDefined} from 'lit/directives/if-defined.js';
 import {property, state} from 'lit/decorators.js';
 import ZnChip from '../chip';
-import ZnHeader from '../header';
+import ZnFormGroup from '../form-group';
 import ZnOption from '../option';
 import ZnPanel from '../panel/panel.component';
 import ZnSelect from '../select';
@@ -19,8 +18,12 @@ import styles from './translation-group.scss';
  * @status experimental
  * @since 1.0
  *
- * The select sits at the top right of the header, opposite the caption. Choosing a language switches every child at
- * once, and each child hides its own select while it is in a group — `grouped` is set on them here.
+ * The fields sit in a `zn-form-group`, so the caption, help text and the language select share its label column and
+ * the fields line up with every other form group around them. Choosing a language switches every child at once, and
+ * each child hides its own select while it is in a group — `grouped` is set on them here.
+ *
+ * The select is searchable. Each option holds its language code as its value, so typing `de` finds German without the
+ * code being on show.
  *
  * Closed, the select carries how many target languages are done — `1/5`. Its options each carry a chip aggregated
  * across the children:
@@ -35,11 +38,11 @@ import styles from './translation-group.scss';
  * The children own their values; this component only chooses which language is shown and reports on what they hold.
  * It reads them back on every child `zn-change`, so the chips and the count follow an edit as it is typed.
  *
- * Extends `zn-panel`, so `caption`, `icon`, `flush`, `transparent` and the `footer` slot behave as they do there.
- * Nested inside another panel, add `inline` to drop the chrome and keep the fields aligned with the surrounding form.
+ * Extends `zn-panel`, so `caption`, `flush`, `transparent` and the `footer` slot behave as they do there. Nested
+ * inside another panel, add `inline` to drop the chrome and keep the fields aligned with the surrounding form.
  *
  * @dependency zn-chip
- * @dependency zn-header
+ * @dependency zn-form-group
  * @dependency zn-option
  * @dependency zn-select
  *
@@ -49,30 +52,33 @@ import styles from './translation-group.scss';
  * @slot actions - Buttons for the bottom of the panel, on the white body rather than the grey footer. They sit on
  *  the right, as zinc's form action rows do; `align="start"` moves one to the left. Write them in the order they
  *  should be read — the sides are set by CSS ordering, so markup order is what a keyboard follows.
- * @slot footer - Content displayed in the grey panel footer. The header belongs to the language select; nothing
- *  else is slotted into it.
+ * @slot footer - Content displayed in the grey panel footer.
  *
  * @csspart base - The component's base wrapper.
+ * @csspart form-group - The form group holding the caption, the language select and the fields.
  * @csspart actions - The row of buttons at the bottom of the body.
- * @csspart language-field - The label and select that choose the language every child is editing.
+ * @csspart language-field - The select that chooses the language every child is editing, in the group's chip slot.
  * @csspart language-select - The select itself.
  */
 export default class ZnTranslationGroup extends ZnPanel {
   static styles: CSSResultGroup = [ZnPanel.styles, unsafeCSS(styles)];
   static dependencies = {
     'zn-chip': ZnChip,
-    'zn-header': ZnHeader,
+    'zn-form-group': ZnFormGroup,
     'zn-option': ZnOption,
     'zn-select': ZnSelect
   };
 
   private readonly _slotController = new HasSlotController(this, 'actions', 'footer');
 
-  /** The caption shown in the panel header. An alias for the inherited `caption`, which wins where both are set. */
+  /** The form group's label. An alias for the inherited `caption`, which wins where both are set. */
   @property() label = '';
 
+  /** Sits under the label, above the language select, as help text does in any other form group. */
+  @property({attribute: 'help-text'}) helpText = '';
+
   /**
-   * Drops the panel chrome — border, background and padding — so the group reads as a section of the form around it
+   * Drops the panel chrome — border, background and padding — so the group reads as a section of the surrounding form
    * rather than a panel of its own. For groups nested inside another panel, where the fields would otherwise sit
    * indented behind a second border.
    */
@@ -149,11 +155,9 @@ export default class ZnTranslationGroup extends ZnPanel {
     return {type: 'error', label: language === 'en' ? 'Empty' : 'English'};
   }
 
-  /** `English (EN)`, or the code alone where the configured name already is the code. */
+  /** The configured name, or the code where `languages` does not name the language. */
   private displayName(language: string): string {
-    const name = this.languages[language] ?? language.toUpperCase();
-    const code = language.toUpperCase();
-    return name.toUpperCase() === code ? name : `${name} (${code})`;
+    return this.languages[language] ?? language.toUpperCase();
   }
 
   /** Children take their language list from the group, so a change to `languages` has to reach them. */
@@ -206,7 +210,7 @@ export default class ZnTranslationGroup extends ZnPanel {
   render() {
     const hasActionsSlot = this._slotController.test('actions');
     const hasFooterSlot = this._slotController.test('footer');
-    const headerCaption = this.caption || this.label;
+    const caption = this.caption || this.label;
 
     // A child's value can carry a language `languages` does not list — server-rendered content outliving a config
     // change. Offer those too, or the translation is stranded in the value with no way to reach it.
@@ -216,7 +220,6 @@ export default class ZnTranslationGroup extends ZnPanel {
       .forEach(code => extra.add(code)));
     const languageCodes = [...Object.keys(this.languages), ...extra];
     const hasMultipleLanguages = languageCodes.length > 1;
-    const hasHeader = Boolean(headerCaption) || hasMultipleLanguages;
 
     // English is the source every other language falls back to, so it is not itself one of the translations counted.
     const targets = languageCodes.filter(code => code !== 'en');
@@ -229,49 +232,50 @@ export default class ZnTranslationGroup extends ZnPanel {
     };
 
     return html`
-      <div class="${classMap({
+      <div part="base" class="${classMap({
         panel: true,
         'panel--flush': this.flush || this.inline,
         'panel--transparent': this.transparent || this.inline,
         'translation-group--inline': this.inline,
-        'panel--has-header': hasHeader,
         'panel--has-actions': hasActionsSlot,
         'panel--has-footer': hasFooterSlot,
       })}">
 
         <div class="panel__inner">
-          ${hasHeader ? html`
-            <zn-header class="panel__header"
-                       caption="${ifDefined(headerCaption || undefined)}"
-                       transparent>
-              ${hasMultipleLanguages ? html`
-                <div slot="actions" class="translation-group__language-field" part="language-field">
-                  <zn-select
-                    label="${this.languageLabel}"
-                    class="translation-group__language-select"
-                    part="language-select"
-                    hoist
-                    .value="${this._activeLanguage}"
-                    @zn-change="${this.handleLanguageSelect}"
-                    @zn-input="${this.handleLanguageInput}">
-                    <zn-chip slot="suffix" type="${summary.type}">${summary.label}</zn-chip>
-                    ${languageCodes.map(code => {
-                      const optionState = this.languageState(code);
-                      return html`
-                        <zn-option value="${code}">
-                          ${this.displayName(code)}
-                          <zn-chip slot="suffix" type="${optionState.type}">${optionState.label}</zn-chip>
-                        </zn-option>`;
-                    })}
-                  </zn-select>
-                </div>` : nothing}
-            </zn-header>` : null}
-
           <div class="panel__content">
             <div class="panel__body">
-              <slot
-                @slotchange="${this.handleSlotChange}"
-                @zn-change="${this.handleChildChange}"></slot>
+              <zn-form-group
+                part="form-group"
+                label="${caption}"
+                help-text="${this.helpText}">
+
+                ${hasMultipleLanguages ? html`
+                  <div slot="chip" class="translation-group__language-field" part="language-field">
+                    <zn-select
+                      label="${this.languageLabel}"
+                      class="translation-group__language-select"
+                      part="language-select"
+                      hoist
+                      search
+                      .value="${this._activeLanguage}"
+                      @zn-change="${this.handleLanguageSelect}"
+                      @zn-input="${this.handleLanguageInput}">
+                      <zn-chip slot="suffix" type="${summary.type}">${summary.label}</zn-chip>
+                      ${languageCodes.map(code => {
+                        const optionState = this.languageState(code);
+                        return html`
+                          <zn-option value="${code}">
+                            ${this.displayName(code)}
+                            <zn-chip slot="suffix" type="${optionState.type}">${optionState.label}</zn-chip>
+                          </zn-option>`;
+                      })}
+                    </zn-select>
+                  </div>` : nothing}
+
+                <slot
+                  @slotchange="${this.handleSlotChange}"
+                  @zn-change="${this.handleChildChange}"></slot>
+              </zn-form-group>
 
               ${hasActionsSlot ? html`
                 <div class="translation-group__actions" part="actions">

package/src/components/translation-group/translation-group.scss

@@ -2,81 +2,15 @@
   display: block;
 }
 
-// The body stacks the fields the select drives, so they take the row gap zn-form-group sets between stacked
-// controls. The slotted children are `display: contents` through the slot, putting them in this same flex flow.
+// The body holds the form group and the actions row; the gap is what separates them.
 .panel__body {
   gap: var(--zn-spacing-medium);
 }
 
-// The header sets its own gap down to the first field; the panel's body padding on top of it would make that one gap
-// the odd one out.
-.panel--has-header .panel__body {
-  padding-top: 0;
-}
-
-.panel__header {
-  padding-bottom: var(--zn-spacing-medium);
-}
-
-.translation-group--inline .panel__header {
-  padding: 0 0 var(--zn-spacing-medium);
-}
-
-// zn-header holds its content row at 36px so a caption sits level with action buttons. The select is taller than
-// that and sets the height on its own, so the row hugs whichever of the two is bigger.
-.panel__header::part(content) {
-  min-height: 0;
-}
-
-// The actions container is a plain block that clips horizontally: its content would sit at the top rather than level
-// with the caption, and a select flush against its right edge would lose the focus ring.
-.panel__header::part(header-right) {
-  display: flex;
-  align-items: center;
-  justify-content: flex-end;
-  overflow: visible;
-}
-
-.translation-group__language-field {
-  display: flex;
-  align-items: center;
-}
-
-// The trigger shows one language, so it sizes to that.
-.translation-group__language-select {
-  width: max-content;
-  max-width: 100%;
-}
-
-// Left alone the display input hands the trigger its default 20-character intrinsic width, however short the language
-// name is. Where field-sizing is unsupported that width is what is left, which only makes the trigger a little wider.
-.translation-group__language-select::part(display-input) {
-  width: auto;
-  min-width: 0;
-  field-sizing: content;
-}
-
-// The popup syncs its width to the trigger, which is now sized to the current language rather than the longest one in
-// the list. zn-select runs the popup with auto-size="vertical", so --auto-size-available-width is never set and the
-// listbox's own max-width is inert — this is the only thing keeping a long list on screen.
-.translation-group__language-select::part(listbox) {
-  min-width: 320px;
-  max-width: calc(100vw - var(--zn-spacing-large));
-}
-
-// The select is chrome in the panel header rather than a field to fill in, so it drops the input's fill and shadow.
-// The border stays, marking it out as something to open.
-.translation-group__language-select::part(combobox) {
-  background-color: transparent;
-  box-shadow: none;
-}
-
-.translation-group__language-select:hover::part(combobox) {
-  background-color: var(--zn-input-background-color-hover);
-}
-
-.translation-group__language-select:focus-within::part(combobox) {
-  box-shadow: 0 0 0 var(--zn-focus-ring-width) var(--zn-input-focus-ring-color);
+// The fields land in the form group's 6-column input grid, but they are assigned to this slot rather than the
+// group's, so its span rules cannot reach them — each takes the full row from here.
+::slotted(:not([slot])) {
+  grid-column: 1 / -1;
 }
 
 // The select's label is its accessible name only; the caption names the section on screen.
@@ -92,11 +26,13 @@
   border: 0;
 }
 
-// Matches zinc's form action rows (.form-actions, zn-form-actions): right-aligned, 16px apart.
+// Matches zinc's form action rows (.form-actions, zn-form-actions): right-aligned, 16px apart. The cap holds the
+// buttons level with the fields' right edge, which zn-form-group sizes to the same container.
 .translation-group__actions {
   display: flex;
   align-items: center;
   gap: var(--zn-spacing-small);
+  max-width: var(--zn-container-lg);
 }
 
 // The spacer, not an auto margin, is what splits the two sides: an auto margin on every right-hand button would open
@@ -114,8 +50,8 @@
   order: 0;
 }
 
-// The panel draws a border between any two body children, and the actions row is the first real element to follow
-// the fields' slot. Matched on .panel--has-actions to out-specify that rule.
+// The panel draws a border between any two body children, and the actions row follows the form group. Matched on
+// .panel--has-actions to out-specify that rule.
 .panel--has-actions .panel__body > .translation-group__actions {
   border: 0;
 }