@kubex/zinc 1.1.98 → 1.1.99

package/src/components/remarkd-editor/remarkd-editor.component.ts

@@ -110,6 +110,8 @@ const SLASH_ITEMS: SlashMenuItem[] = BLOCK_TYPES.map(item => item.image || item.
  * @csspart image-controls - The caption / alignment / size panel shown when an image block is clicked.
  * @csspart include - The chip rendered in place of an `include::` directive.
  * @csspart include-picker - The inline Include picker opened from the toolbar or "/include".
+ *
+ * @cssproperty --remarkd-editor-max-height - The tallest the editor grows before its body scrolls. Defaults to `100dvh`.
  */
 export default class ZnRemarkdEditor extends ZincElement implements ZincFormControl {
   static styles: CSSResultGroup = unsafeCSS(styles);
@@ -165,6 +167,8 @@ export default class ZnRemarkdEditor extends ZincElement implements ZincFormCont
   private dragStartX = 0;
   private dragStartY = 0;
   private dragGhost: HTMLElement | null = null;
+  private dragPointerY = 0;
+  private autoScrollFrame: number | null = null;
 
   /** The name of the control, submitted as part of form data. */
   @property() name = '';
@@ -440,14 +444,14 @@ export default class ZnRemarkdEditor extends ZincElement implements ZincFormCont
     this.updateBlocks(blocks);
   }
 
-  private startEdit(index: number, draft?: string) {
+  private startEdit(index: number, draft?: string, align: 'nearest' | 'center' = 'nearest') {
     if (this.disabled || this.readonly) return;
     this.editingDraft = draft ?? this.blocks[index] ?? '';
     this.editingIndex = index;
     this.imageEdit = null;
     this.editShell = this.computeEditShell(this.editingDraft);
     this.slashController.close();
-    void this.focusInput();
+    void this.focusInput(align);
   }
 
   private updateImageEdit(patch: Partial<ImageBlockData>) {
@@ -507,24 +511,83 @@ export default class ZnRemarkdEditor extends ZincElement implements ZincFormCont
     return '';
   }
 
-  private async focusInput() {
+  private async focusInput(align: 'nearest' | 'center' = 'nearest') {
     await this.updateComplete;
     const input = this.shadowRoot?.querySelector<HTMLTextAreaElement>('.remarkd-editor__input');
     if (input) {
       // Each edit renders its own textarea, so the slash menu is re-pointed at it.
       this.slashController.attach(input);
       this.autosize(input);
-      input.focus();
+      // preventScroll because the browser's own focus scroll walks every scrollable
+      // ancestor — including the surrounding page panel. reveal() stays in the editor.
+      input.focus({preventScroll: true});
       input.setSelectionRange(input.value.length, input.value.length);
+      this.reveal(input, align);
     }
     this.suppressBlurCommit = false;
   }
 
+  /**
+   * Scrolls the editor's own body to bring `el` into view. Never `scrollIntoView()` and
+   * never `focus()` without preventScroll: both walk every scrollable ancestor, and an
+   * `overflow: hidden`/`auto` panel around the editor is scrollable too — that shifts a
+   * container the user never asked to move.
+   */
+  private reveal(el: Element | null | undefined, align: 'nearest' | 'center' = 'nearest') {
+    const body = this.shadowRoot?.querySelector('.remarkd-editor__body');
+    if (!el || !body) return;
+
+    const target = el.getBoundingClientRect();
+    const view = body.getBoundingClientRect();
+
+    // scrollTop clamps itself, so an overshoot at either end lands at the limit.
+    if (align === 'center') {
+      // Taller than the view — a large image, say — can't be centred without hiding its
+      // top, so anchor the top and let the rest run off the bottom.
+      body.scrollTop += target.height > view.height
+        ? target.top - view.top
+        : (target.top + target.height / 2) - (view.top + view.height / 2);
+    } else if (target.top < view.top) {
+      body.scrollTop += target.top - view.top;
+    } else if (target.bottom > view.bottom) {
+      body.scrollTop += target.bottom - view.bottom;
+    }
+  }
+
+  private async revealAfterUpdate(selector: string, align: 'nearest' | 'center' = 'nearest') {
+    await this.updateComplete;
+    this.reveal(this.shadowRoot?.querySelector(selector), align);
+  }
+
+  /**
+   * Centres a block added without opening an editor. An image has no height until it
+   * loads, so the first pass scrolls against a layout that is still short — the second
+   * pass corrects it once the real dimensions are in.
+   */
+  private async revealBlock(index: number) {
+    await this.updateComplete;
+    const blockAt = () => this.shadowRoot?.querySelectorAll('.remarkd-editor__block')[index];
+    const block = blockAt();
+    if (!block) return;
+    this.reveal(block, 'center');
+
+    const loading = [...block.querySelectorAll('img')].filter(img => !img.complete);
+    if (!loading.length) return;
+
+    await Promise.all(loading.map(img => new Promise<void>(resolve => {
+      img.addEventListener('load', () => resolve(), {once: true});
+      img.addEventListener('error', () => resolve(), {once: true});
+    })));
+    await new Promise(requestAnimationFrame);
+    this.reveal(blockAt(), 'center');
+  }
+
   private addBlockAt(index: number, content: string) {
     if (this.disabled || this.readonly) return;
     const blocks = [...this.blocks];
     blocks.splice(index, 0, content);
     this.updateBlocks(blocks);
+    void this.revealBlock(index);
   }
 
   private deleteBlock(index: number) {
@@ -540,7 +603,7 @@ export default class ZnRemarkdEditor extends ZincElement implements ZincFormCont
     const blocks = [...this.blocks];
     blocks.splice(index, 0, '');
     this.blocks = blocks;
-    this.startEdit(index, prefill);
+    this.startEdit(index, prefill, 'center');
   }
 
   /**
@@ -714,10 +777,56 @@ export default class ZnRemarkdEditor extends ZincElement implements ZincFormCont
       document.body.style.cursor = 'grabbing';
     }
 
+    this.dragPointerY = e.clientY;
     this.moveDragGhost(e.clientX, e.clientY);
     this.dropIndicator = this.insertionIndexFromY(e.clientY);
+    this.autoScrollFrame ??= requestAnimationFrame(this.stepAutoScroll);
   };
 
+  /**
+   * Holding the pointer near a scroll edge keeps the content moving, so a block can
+   * be dragged past the visible slice of a long document. Runs per frame rather than
+   * per pointermove — a pointer parked at the edge stops emitting moves.
+   */
+  private stepAutoScroll = () => {
+    this.autoScrollFrame = null;
+    if (this.dragIndex === null || !this.autoScroll()) return;
+    // The content moved under a possibly stationary pointer, so the drop target shifts.
+    this.dropIndicator = this.insertionIndexFromY(this.dragPointerY);
+    this.autoScrollFrame = requestAnimationFrame(this.stepAutoScroll);
+  };
+
+  /** Scrolls the editor body, falling through to the page once the body is at its limit. */
+  private autoScroll(): boolean {
+    const body = this.shadowRoot?.querySelector('.remarkd-editor__body');
+    if (body) {
+      const {top, bottom} = body.getBoundingClientRect();
+      const delta = this.edgeScrollDelta(top, bottom);
+      const before = body.scrollTop;
+      if (delta) {
+        body.scrollTop += delta;
+        if (body.scrollTop !== before) return true;
+      }
+    }
+
+    const pageDelta = this.edgeScrollDelta(0, window.innerHeight);
+    if (!pageDelta) return false;
+    const before = window.scrollY;
+    window.scrollBy(0, pageDelta);
+    return window.scrollY !== before;
+  }
+
+  /** Scroll step for this frame: nothing until the pointer is within `edge` of a boundary. */
+  private edgeScrollDelta(top: number, bottom: number): number {
+    const edge = 56;
+    const max = 18;
+    const ramp = (depth: number) => Math.ceil((Math.min(depth, edge) / edge) * max);
+
+    if (this.dragPointerY < top + edge) return -ramp(top + edge - this.dragPointerY);
+    if (this.dragPointerY > bottom - edge) return ramp(this.dragPointerY - (bottom - edge));
+    return 0;
+  }
+
   private handleDragPointerUp = (e: PointerEvent) => {
     const from = this.dragIndex;
     let to = from !== null ? (this.dropIndicator ?? this.insertionIndexFromY(e.clientY)) : null;
@@ -732,6 +841,8 @@ export default class ZnRemarkdEditor extends ZincElement implements ZincFormCont
 
   private cancelDrag = () => {
     this.pendingDragHandle = null;
+    if (this.autoScrollFrame !== null) cancelAnimationFrame(this.autoScrollFrame);
+    this.autoScrollFrame = null;
     document.removeEventListener('pointermove', this.handleDragPointerMove);
     document.removeEventListener('pointerup', this.handleDragPointerUp);
     document.removeEventListener('pointercancel', this.cancelDrag);
@@ -761,6 +872,7 @@ export default class ZnRemarkdEditor extends ZincElement implements ZincFormCont
     if (this.disabled || this.readonly) return;
     this.includePickerIndex = null;
     this.imagePickerIndex = index;
+    void this.revealAfterUpdate('.remarkd-editor__image-picker', 'center');
   }
 
   private pickInclude(index: number) {
@@ -769,6 +881,7 @@ export default class ZnRemarkdEditor extends ZincElement implements ZincFormCont
     this.includeQuery = '';
     this.includePickerIndex = index;
     void this.loadIncludeOptions();
+    void this.revealAfterUpdate('.remarkd-editor__include-picker', 'center');
   }
 
   private closeIncludePicker = () => {

package/src/components/remarkd-editor/remarkd-editor.scss

@@ -4,10 +4,16 @@
 
 :host {
   display: block;
+  overflow: hidden;
 }
 
 .remarkd-editor {
   position: relative;
+  display: flex;
+  flex-direction: column;
+  // A long document scrolls the body instead of growing the page past one screenful,
+  // which also keeps the toolbar in reach.
+  max-height: var(--remarkd-editor-max-height, 100dvh);
   border: 1px solid rgb(var(--zn-border-color));
   border-radius: var(--zn-border-radius);
   background-color: rgba(var(--zn-panel), var(--zn-panel-opacity));
@@ -15,6 +21,7 @@
 
 .remarkd-editor__toolbar {
   display: flex;
+  flex: none;
   gap: 2px;
   flex-wrap: wrap;
   padding: var(--zn-spacing-x-small);
@@ -24,6 +31,7 @@
 .remarkd-editor__body {
   padding: var(--zn-spacing-large) var(--zn-spacing-large) var(--zn-spacing-large) 52px;
   min-height: 10rem;
+  overflow-y: auto;
 }
 
 // Raw mode has no gutter handles, so it reclaims the left padding.
@@ -92,7 +100,6 @@
 }
 
 
-
 .remarkd-editor__drag-handle {
   display: inline-flex;
   align-items: center;

package/src/components/remarkd-editor/remarkd-editor.test.ts

@@ -118,6 +118,102 @@ Second"></zn-remarkd-editor>`);
     await expectNamedIconButtons(el, el.shadowRoot!.querySelector('.remarkd-editor__image-controls')!);
   });
 
+  /** A document tall enough to overflow the editor's max height. */
+  const longValue = Array.from({length: 60}, (_, i) => `Paragraph ${i}`).join('\n\n');
+
+  it('should not grow taller than the viewport', async () => {
+    const el = await fixture<ZnRemarkdEditor>(html`
+      <zn-remarkd-editor value=${longValue}></zn-remarkd-editor>`);
+    expect(el.getBoundingClientRect().height).to.be.at.most(window.innerHeight + 1);
+  });
+
+  /** Adds a block below the middle block via its gutter button. */
+  async function addBlockMidDocument(el: ZnRemarkdEditor) {
+    const blocks = el.shadowRoot!.querySelectorAll('.remarkd-editor__block');
+    blocks[Math.floor(blocks.length / 2)].querySelector('.remarkd-editor__actions zn-button')!
+      .dispatchEvent(new MouseEvent('click', {bubbles: true, composed: true, cancelable: true}));
+    await waitUntil(() => el.shadowRoot!.querySelector('.remarkd-editor__input'), 'no block opened');
+  }
+
+  it('should centre a newly added block in its own body', async () => {
+    const el = await fixture<ZnRemarkdEditor>(html`
+      <zn-remarkd-editor value=${longValue}></zn-remarkd-editor>`);
+    const body = el.shadowRoot!.querySelector('.remarkd-editor__body')!;
+    await addBlockMidDocument(el);
+
+    const bodyBox = body.getBoundingClientRect();
+    const inputBox = el.shadowRoot!.querySelector('.remarkd-editor__input')!.getBoundingClientRect();
+    expect(body.scrollTop, 'the body never scrolled').to.be.greaterThan(0);
+    expect(Math.abs((inputBox.top - bodyBox.top) - (bodyBox.bottom - inputBox.bottom)),
+      'the new block is not centred').to.be.lessThan(60);
+  });
+
+  it('should not scroll an enclosing panel when a block is added', async () => {
+    // An `overflow: hidden` panel has no scrollbar but is still scrollable in code, so
+    // scrollIntoView() or a plain focus() would shift it with no way to scroll back.
+    const panel = await fixture<HTMLDivElement>(html`
+      <div style="height: 200px; overflow: hidden">
+        <zn-remarkd-editor value=${longValue}></zn-remarkd-editor>
+        <div style="height: 900px"></div>
+      </div>`);
+    const el = panel.querySelector<ZnRemarkdEditor>('zn-remarkd-editor')!;
+    await el.updateComplete;
+    const body = el.shadowRoot!.querySelector('.remarkd-editor__body')!;
+    await addBlockMidDocument(el);
+
+    expect(body.scrollTop, 'the editor body should still scroll').to.be.greaterThan(0);
+    expect(panel.scrollTop, 'the enclosing panel was scrolled').to.equal(0);
+  });
+
+  it('should not scroll an enclosing scroller when an image block is added', async () => {
+    const panel = await fixture<HTMLDivElement>(html`
+      <div style="height: 200px; overflow: auto">
+        <zn-remarkd-editor value=${longValue}></zn-remarkd-editor>
+        <div style="height: 900px"></div>
+      </div>`);
+    const el = panel.querySelector<ZnRemarkdEditor>('zn-remarkd-editor')!;
+    await el.updateComplete;
+    const body = el.shadowRoot!.querySelector('.remarkd-editor__body')!;
+    expect(panel.scrollHeight - panel.clientHeight, 'the panel needs room to scroll')
+      .to.be.greaterThan(0);
+
+    // A 1x1 gif: an image block whose height only lands once it loads.
+    const src = 'data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7';
+    el.value = `${longValue}\n\nimage::${src}[pixel]`;
+    await el.updateComplete;
+    await waitUntil(() => el.shadowRoot!.querySelector('.remarkd-editor__block img'), 'no image block');
+
+    expect(panel.scrollTop, 'the enclosing scroller was scrolled').to.equal(0);
+    expect(body.scrollTop, 'the body should be scrollable').to.be.at.least(0);
+  });
+
+  it('should keep scrolling while a drag is held at the edge', async () => {
+    const el = await fixture<ZnRemarkdEditor>(html`
+      <zn-remarkd-editor value=${longValue}></zn-remarkd-editor>`);
+    const body = el.shadowRoot!.querySelector('.remarkd-editor__body')!;
+    const handle = el.shadowRoot!.querySelectorAll('.remarkd-editor__block')[1]
+      .querySelector('.remarkd-editor__drag-handle')!;
+    const from = handle.getBoundingClientRect();
+    const drag = (type: string, clientY: number, target: EventTarget, buttons = 1) =>
+      target.dispatchEvent(new PointerEvent(type, {
+        bubbles: true, composed: true, cancelable: true,
+        clientX: Math.round(from.left + 5), clientY, button: 0, buttons,
+      }));
+
+    drag('pointerdown', Math.round(from.top + 5), handle);
+    drag('pointermove', Math.round(from.top + 20), document);
+    expect(el.shadowRoot!.querySelector('.remarkd-editor__ghost'), 'the drag never started').to.exist;
+
+    // Park the pointer in the bottom edge zone — the frame loop scrolls without further moves.
+    drag('pointermove', Math.round(body.getBoundingClientRect().bottom - 20), document);
+    await waitUntil(() => body.scrollTop > 0, 'a drag held at the edge never scrolled');
+
+    drag('pointercancel', 0, document, 0);
+    const settled = body.scrollTop;
+    await new Promise(resolve => setTimeout(resolve, 100));
+    expect(body.scrollTop, 'scrolling continued after the drag ended').to.equal(settled);
+  });
+
   it('should open zn-slash-menu with the block types when "/" starts an empty block', async () => {
     const el = await fixture<ZnRemarkdEditor>(html`
       <zn-remarkd-editor value="Hello"></zn-remarkd-editor>`);

package/src/components/scroll-container/scroll-container.component.ts

@@ -21,11 +21,14 @@ import styles from './scroll-container.scss';
  *
  * @csspart base - The component's base wrapper.
  *
- * @cssproperty --example - An example CSS custom property.
+ * @cssproperty --zn-scroll-container-height - The height and maximum height of the scroll container.
  */
 export default class ZnScrollContainer extends ZincElement {
   static styles: CSSResultGroup = unsafeCSS(styles);
 
+  /** The height and maximum height of the scroll container. */
+  @property({type: String}) height = '';
+
   @property({attribute: 'start-scrolled', type: Boolean, reflect: true}) startScrolled: boolean = false;
 
   @query('.scroll-container')
@@ -44,6 +47,17 @@ export default class ZnScrollContainer extends ZincElement {
     }
   }
 
+  protected updated(changedProperties: PropertyValues) {
+    super.updated(changedProperties);
+    if (changedProperties.has('height')) {
+      if (this.height) {
+        this.style.setProperty('--zn-scroll-container-height-property', this.height);
+      } else {
+        this.style.removeProperty('--zn-scroll-container-height-property');
+      }
+    }
+  }
+
   disconnectedCallback() {
     super.disconnectedCallback();
     if (this._footerHeightFrame !== null) {

package/src/components/scroll-container/scroll-container.scss

@@ -2,8 +2,10 @@
 
 :host {
   @include wc.scrollbars;
-  
-  display: contents;
+
+  display: block;
+  height: var(--zn-scroll-container-height-property, var(--zn-scroll-container-height, 100%));
+  max-height: var(--zn-scroll-container-height-property, var(--zn-scroll-container-height, 100%));
   --zn-scroll-footer-height: 0px;
   --zn-scroll-header-height: 0px;
 }

package/src/components/scroll-container/scroll-container.test.ts

@@ -7,4 +7,17 @@ describe('<zn-scroll-container>', () => {
 
     expect(el).to.exist;
   });
+
+  it('should render as a block-level container', async () => {
+    const el = await fixture(html` <zn-scroll-container></zn-scroll-container> `);
+
+    expect(getComputedStyle(el).display).to.equal('block');
+  });
+
+  it('should apply height as the height and maximum height', async () => {
+    const el = await fixture(html` <zn-scroll-container height="240px"></zn-scroll-container> `);
+
+    expect(getComputedStyle(el).height).to.equal('240px');
+    expect(getComputedStyle(el).maxHeight).to.equal('240px');
+  });
 });

package/src/components/slideout/slideout.component.ts

@@ -4,6 +4,7 @@ import {type CSSResultGroup, html, type PropertyValues, unsafeCSS} from 'lit';
 import {LocalizeController} from "../../utilities/localize";
 import {property, query} from 'lit/decorators.js';
 import {getAnimation, setDefaultAnimation} from "../../utilities/animation-registry";
+import {idSelector} from "../../utilities/query";
 import {unlockBodyScrolling} from "../../internal/scroll";
 import ZincElement from '../../internal/zinc-element';
 import ZnButton from "../button";
@@ -83,7 +84,7 @@ export default class ZnSlideout extends ZincElement {
     this.shadowRoot?.addEventListener('click', this.closeClickHandler);
 
     if (this.trigger) {
-      const trigger = this.parentNode?.querySelector('#' + this.trigger);
+      const trigger = this.parentNode?.querySelector(idSelector(this.trigger));
       if (trigger) {
         trigger.addEventListener('click', () => this.show());
       }
@@ -98,7 +99,7 @@ export default class ZnSlideout extends ZincElement {
     this.removeEventListener('click', this.closeClickHandler);
 
     if (this.trigger) {
-      const trigger = this.parentElement?.querySelector('#' + this.trigger);
+      const trigger = this.parentElement?.querySelector(idSelector(this.trigger));
       if (trigger) {
         trigger.removeEventListener('click', () => this.show());
       }

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

@@ -19,7 +19,6 @@
   @include wc.text-style(h1);
 
   min-width: 0;
-  overflow: hidden;
   text-overflow: ellipsis;
   white-space: nowrap;
 }

package/src/components/tile/tile.scss

@@ -10,6 +10,7 @@
   align-items: center;
   justify-content: space-between;
   min-height: 48px;
+  padding: var(--zn-base-gap);
   column-gap: var(--zn-spacing-large);
 
   font-size: var(--zn-text-table-content-font-size);
@@ -23,14 +24,15 @@
   &--has-properties,
   &--has-actions {
     padding-inline: var(--zn-base-gap);
+    min-height: 85px;
   }
 
   &--has-description#{&}--has-caption {
-    padding-block: var(--zn-spacing-small);
+    padding-block: var(--zn-base-gap);
   }
 
   &--has-image {
-    padding: var(--zn-spacing-small);
+    padding: var(--zn-base-gap);
   }
 
   &--has-href {

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

@@ -0,0 +1,22 @@
+import '../../../dist/zn.min.js';
+import { expect, fixture, html } from '@open-wc/testing';
+import type ZnInlineEdit from '../inline-edit/inline-edit.component';
+import type ZnTranslations from '../translations/translations.component';
+
+describe('<zn-translation-group>', () => {
+  // The group syncs its children from its own first update, which runs before theirs, so a child's
+  // pending value attribute must survive the language keys the group adds.
+  it("keeps a child's rendered value when it syncs the group language", async () => {
+    const group = await fixture(html`
+      <zn-translation-group label="Text" .languages=${{en: 'English', fr: 'French'}}>
+        <zn-translations name="heading" value='{"en":"Chat to us"}'></zn-translations>
+      </zn-translation-group>`);
+
+    const child = group.querySelector<ZnTranslations>('zn-translations')!;
+    await child.updateComplete;
+
+    expect(child.values).to.deep.equal({en: 'Chat to us'});
+    const input = child.shadowRoot!.querySelector<ZnInlineEdit>('zn-inline-edit')!;
+    expect(input.value).to.equal('Chat to us');
+  });
+});

package/src/components/translations/translations.component.ts

@@ -150,15 +150,30 @@ export default class ZnTranslations extends ZincElement implements ZincFormContr
 
   /** Adds a language key to this component's values if not already present. Used by zn-translation-group. */
   public addLanguageKey(languageCode: string) {
-    if (!Object.prototype.hasOwnProperty.call(this.values, languageCode)) {
-      this.values = {...this.values, [languageCode]: ''};
+    const values = this.pendingValues();
+    if (!Object.prototype.hasOwnProperty.call(values, languageCode)) {
+      this.values = {...values, [languageCode]: ''};
       this.updateValue();
     }
   }
 
   /** Returns all language codes that have values. */
   public getValueLanguages(): string[] {
-    return Object.keys(this.values);
+    return Object.keys(this.pendingValues());
+  }
+
+  /**
+   * `values`, falling back to the `value` attribute it is built from while that is still pending. A parent
+   * zn-translation-group syncs its children from its own first update, which runs before theirs, so reading
+   * `values` alone would see it empty and overwrite the value the server rendered.
+   */
+  private pendingValues(): Record<string, string> {
+    if (Object.keys(this.values).length > 0) return this.values;
+    try {
+      return JSON.parse(this.value || '{}') as Record<string, string>;
+    } catch {
+      return this.values;
+    }
   }
 
   disconnectedCallback() {

package/src/form-control.scss

@@ -123,6 +123,8 @@
   margin-top: var(--zn-spacing-3x-small);
 }
 
-.form-control--checkbox-contained-wrapper {
+/* Let contained radios/checkboxes fill their grid row so cards in a row match height. */
+.form-control--checkbox-contained-wrapper,
+.form-control--radio-contained-wrapper {
   height: 100%;
 }

package/src/internal/conditional.ts

@@ -1,4 +1,4 @@
-import {deepQuerySelectorAll} from '../utilities/query';
+import {deepQuerySelectorAll, idSelector} from '../utilities/query';
 import type {ReactiveController, ReactiveControllerHost} from 'lit';
 
 export interface ConditionalHost {
@@ -26,7 +26,7 @@ export class ConditionalController implements ReactiveController {
     const ids = this.host.conditional.split(',').map(id => id.trim());
 
     ids.forEach(id => {
-      const byId = deepQuerySelectorAll(`#${id}`, document.documentElement, '') as (Element & {
+      const byId = deepQuerySelectorAll(idSelector(id), document.documentElement, '') as (Element & {
         value: string | string[];
       })[];
       const byName = deepQuerySelectorAll(`[name="${id}"]`, document.documentElement, '') as (Element & {

package/src/internal/form.ts

@@ -1,4 +1,5 @@
 import {getFormNavigationController} from "./form-navigation";
+import {idSelector} from "../utilities/query";
 import {Store} from "./storage";
 import type {ReactiveController, ReactiveControllerHost} from "lit";
 import type {ZincFormControl} from "./zinc-element";
@@ -256,7 +257,7 @@ export class FormControlController implements ReactiveController {
 
         if (formId) {
           const root = input.getRootNode() as Document | ShadowRoot | HTMLElement;
-          const form = root.querySelector(`#${formId}`);
+          const form = root.querySelector(idSelector(formId));
 
           if (form) {
             return form as HTMLFormElement;

package/src/internal/selection-card.ts

@@ -0,0 +1,19 @@
+/** Where a selection card renders its image, relative to the card's text. */
+export type SelectionCardImagePosition = 'top' | 'right' | 'bottom' | 'left';
+
+/**
+ * Where a selection card renders its radio/checkbox indicator. `start` keeps the standard
+ * inline position; `none` hides the indicator so the card itself shows the selected state.
+ */
+export type SelectionCardControlPosition =
+  | 'start'
+  | 'none'
+  | 'top-left'
+  | 'top-center'
+  | 'top-right'
+  | 'center-left'
+  | 'center'
+  | 'center-right'
+  | 'bottom-left'
+  | 'bottom-center'
+  | 'bottom-right';