@boostdev/design-system-components 2.7.1 → 2.11.0

package/src/web-components/interaction/form/bds-textarea.spec.ts

@@ -52,4 +52,75 @@ describe('bds-textarea', () => {
   it('is form-associated', () => {
     expect(BdsTextarea.formAssociated).toBe(true);
   });
+
+  it('renders a label associated with the textarea via for/id', async () => {
+    const el = await fixture('<bds-textarea name="message" label="Message"></bds-textarea>');
+    const textarea = el.shadowRoot!.querySelector<HTMLTextAreaElement>('textarea')!;
+    const label = el.shadowRoot!.querySelector('label')!;
+    expect(label.textContent?.trim()).toContain('Message');
+    expect(textarea.id).toBeTruthy();
+    expect(label.getAttribute('for')).toBe(textarea.id);
+    cleanup(el);
+  });
+
+  it('renders no label when label attribute is unset', async () => {
+    const el = await fixture('<bds-textarea name="message"></bds-textarea>');
+    expect(el.shadowRoot!.querySelector('label')).toBeNull();
+    cleanup(el);
+  });
+
+  it('sets aria-invalid and renders an error message when error is set', async () => {
+    const el = await fixture('<bds-textarea name="message" error="Message is required"></bds-textarea>');
+    const textarea = el.shadowRoot!.querySelector<HTMLTextAreaElement>('textarea')!;
+    const errorMsg = el.shadowRoot!.querySelector('.message--error');
+    expect(textarea.getAttribute('aria-invalid')).toBe('true');
+    expect(errorMsg?.textContent?.trim()).toBe('Message is required');
+    expect(textarea.getAttribute('aria-describedby')).toBe(errorMsg!.id);
+    cleanup(el);
+  });
+
+  it('renders a hint message when hint is set (no error)', async () => {
+    const el = await fixture('<bds-textarea name="message" hint="Max 200 characters"></bds-textarea>');
+    const textarea = el.shadowRoot!.querySelector<HTMLTextAreaElement>('textarea')!;
+    const hint = el.shadowRoot!.querySelector('.message--hint');
+    expect(hint?.textContent?.trim()).toBe('Max 200 characters');
+    expect(textarea.getAttribute('aria-describedby')).toBe(hint!.id);
+    cleanup(el);
+  });
+
+  it('fires bds-input on keystroke with the current value in detail', async () => {
+    const el = await fixture('<bds-textarea name="message"></bds-textarea>');
+    const values: string[] = [];
+    el.addEventListener('bds-input', (e: Event) => {
+      values.push((e as CustomEvent).detail.value);
+    });
+    const textarea = el.shadowRoot!.querySelector<HTMLTextAreaElement>('textarea')!;
+    textarea.value = 'Hi';
+    textarea.dispatchEvent(new Event('input', { bubbles: true }));
+    expect(values).toEqual(['Hi']);
+    cleanup(el);
+  });
+
+  it('fires a composed bds-change event that crosses the shadow boundary', async () => {
+    const el = await fixture('<bds-textarea name="message"></bds-textarea>');
+    const values: string[] = [];
+    // A native `change` on the inner textarea is not composed and never
+    // reaches a listener on the host; `bds-change` is re-dispatched so it does.
+    el.addEventListener('bds-change', (e: Event) => {
+      values.push((e as CustomEvent).detail.value);
+    });
+    const textarea = el.shadowRoot!.querySelector<HTMLTextAreaElement>('textarea')!;
+    textarea.value = 'Hello world';
+    textarea.dispatchEvent(new Event('change', { bubbles: true }));
+    expect(values).toEqual(['Hello world']);
+    cleanup(el);
+  });
+
+  it('restores the initial value on form reset', async () => {
+    const el = await fixture('<bds-textarea name="message" value="Initial text"></bds-textarea>') as BdsTextarea;
+    el.value = 'Something else entirely';
+    el.formResetCallback();
+    expect(el.value).toBe('Initial text');
+    cleanup(el);
+  });
 });

package/src/web-components/interaction/form/bds-textarea.ts

@@ -11,20 +11,33 @@ import { LitElement, css, html } from 'lit';
  *   value       — text value
  *   placeholder — placeholder text
  *   rows        — number of visible rows (default: 4)
+ *   label       — visible label text
+ *   hint        — helper text shown below the textarea
+ *   error       — error message; when set the textarea enters error state
  *   required    — boolean
  *   disabled    — boolean
  *
  * Events:
- *   input  — native input event
- *   change — native change event
+ *   bds-input  — fired on every keystroke; `detail: { value: string }`
+ *   bds-change — fired when the value is committed; `detail: { value: string }`
  *
  * @example
- * <bds-textarea name="message" placeholder="Enter message…" rows="6"></bds-textarea>
+ * <bds-textarea name="message" label="Message" placeholder="Enter message…" rows="6"></bds-textarea>
  */
 export class BdsTextarea extends LitElement {
   static formAssociated = true;
 
   static styles = css`
+    /* Shadow DOM does not inherit the global box-sizing reset, so set it
+       here; otherwise elements with an explicit size + padding size as
+       content-box and layouts drift from the React (light-DOM) versions. */
+    :host,
+    *,
+    *::before,
+    *::after {
+      box-sizing: border-box;
+    }
+
     :host {
       display: block;
     }
@@ -34,15 +47,29 @@ export class BdsTextarea extends LitElement {
       pointer-events: none;
     }
 
+    .label {
+      display: block;
+      font-size: var(--bds-font_size--body--s);
+      font-family: var(--bds-font_family--body);
+      font-weight: var(--bds-font_weight--semibold);
+      color: var(--bds-color_on-bg);
+      margin-block-end: var(--bds-space_xxs);
+    }
+
+    .required {
+      color: var(--bds-color_error);
+      margin-inline-start: var(--bds-space_xxxs);
+    }
+
     .textarea {
       inline-size: 100%;
       font-family: var(--bds-font_family--body);
       font-size: var(--bds-font_size--body);
       line-height: var(--bds-font_line-height--body);
       padding: var(--bds-space_s);
-      border: none;
-      --bdc_color: var(--textarea_border-color, currentcolor);
-      --bdc-outline_radius: var(--bds-border_radius--xs);
+      border: var(--textarea_border, none);
+      --bdc_color: currentcolor;
+      --bdc-outline_radius: var(--bdc-outline_radius--l);
 
       border-radius: var(--textarea_radius, var(--bdc-outline_radius));
       box-shadow: inset 0 0 0 var(--bdc-outline_width) var(--bdc_color), var(--textarea_shadow, var(--bdc-outline_shadow));
@@ -69,6 +96,29 @@ export class BdsTextarea extends LitElement {
       cursor: not-allowed;
       resize: none;
     }
+
+    :host([error]) .textarea {
+      --bdc_color: var(--bdc_color--error);
+    }
+
+    :host([error]) .textarea:focus {
+      --bdc_color: var(--bdc_color--error);
+    }
+
+    .message {
+      margin-block-start: var(--bds-space_xxs);
+      font-size: var(--bds-font_size--body--s);
+      font-family: var(--bds-font_family--body);
+    }
+
+    .message--error {
+      color: var(--bds-color_error);
+    }
+
+    .message--hint {
+      color: var(--bds-color_on-bg--subtle);
+      font-style: italic;
+    }
   `;
 
   static properties = {
@@ -76,6 +126,9 @@ export class BdsTextarea extends LitElement {
     value:       { type: String },
     placeholder: { type: String },
     rows:        { type: Number },
+    label:       { type: String },
+    hint:        { type: String },
+    error:       { type: String, reflect: true },
     required:    { type: Boolean, reflect: true },
     disabled:    { type: Boolean, reflect: true },
   };
@@ -84,10 +137,15 @@ export class BdsTextarea extends LitElement {
   declare value: string;
   declare placeholder: string;
   declare rows: number;
+  declare label: string;
+  declare hint: string | undefined;
+  declare error: string | undefined;
   declare required: boolean;
   declare disabled: boolean;
 
   private _internals!: ElementInternals;
+  private readonly _uid = Math.random().toString(36).slice(2, 8);
+  private _initialValue = '';
 
   constructor() {
     super();
@@ -96,10 +154,16 @@ export class BdsTextarea extends LitElement {
     this.value = '';
     this.placeholder = '';
     this.rows = 4;
+    this.label = '';
     this.required = false;
     this.disabled = false;
   }
 
+  connectedCallback() {
+    super.connectedCallback();
+    this._initialValue = this.value;
+  }
+
   updated(changed: Map<string, unknown>) {
     super.updated(changed);
     if (changed.has('value')) {
@@ -108,17 +172,45 @@ export class BdsTextarea extends LitElement {
   }
 
   formResetCallback() {
-    this.value = '';
-    this._internals.setFormValue?.(null);
+    this.value = this._initialValue;
+    this._internals.setFormValue?.(this.value || null);
   }
 
   private _handleInput(e: Event) {
     this.value = (e.target as HTMLTextAreaElement).value;
+    this.dispatchEvent(new CustomEvent('bds-input', {
+      detail: { value: this.value },
+      bubbles: true,
+      composed: true,
+    }));
+  }
+
+  private _handleChange(e: Event) {
+    this.value = (e.target as HTMLTextAreaElement).value;
+    this.dispatchEvent(new CustomEvent('bds-change', {
+      detail: { value: this.value },
+      bubbles: true,
+      composed: true,
+    }));
   }
 
   render() {
+    const id = `bds-textarea-${this._uid}`;
+    const hintId = `${id}-hint`;
+    const errorId = `${id}-error`;
+    const describedBy = [this.error && errorId, this.hint && hintId].filter(Boolean).join(' ') || undefined;
+
     return html`
+      ${this.label
+        ? html`
+            <label class="label" for=${id}>
+              ${this.label}
+              ${this.required ? html`<span class="required" aria-hidden="true">*</span>` : ''}
+            </label>
+          `
+        : ''}
       <textarea
+        id=${id}
         class="textarea"
         name=${this.name}
         .value=${this.value}
@@ -126,8 +218,17 @@ export class BdsTextarea extends LitElement {
         rows=${this.rows}
         ?required=${this.required}
         ?disabled=${this.disabled}
+        aria-invalid=${this.error ? 'true' : 'false'}
+        aria-describedby=${describedBy ?? ''}
+        aria-required=${this.required ? 'true' : 'false'}
         @input=${this._handleInput}
+        @change=${this._handleChange}
       ></textarea>
+      ${this.error
+        ? html`<p id=${errorId} class="message message--error" role="alert">${this.error}</p>`
+        : this.hint
+          ? html`<p id=${hintId} class="message message--hint">${this.hint}</p>`
+          : ''}
     `;
   }
 }

package/src/web-components/layout/BdsGrid.mdx

@@ -50,6 +50,7 @@ Numeric `column-span="n"` is literal — it does not adapt. Use named values for
 | `is-masonry`      | boolean                                        | `false`  | Enables masonry layout (CSS Grid Level 3 "grid-lanes"). Uses native CSS when supported, otherwise runs a JS polyfill. |
 | `auto-span-media` | boolean                                        | `false`  | Child `<bds-grid-item>`s without an explicit `column-span` resolve their span from the intrinsic aspect ratio of their first `<img>`/`<video>` descendant. See [Aspect-ratio auto-span](#aspect-ratio-auto-span). |
 | `masonry-preferred-column-span` | named span \| number             | —        | In masonry mode, items without an explicit `column-span` try to span this value, demoting to fit at row ends. Accepts the same named values as `column-span` (`"half"`, `"one-third"`, etc.). See [Masonry preferred column span](#masonry-preferred-column-span). |
+| `masonry-row-unit-px` | number                                     | —        | Masonry only. Manual override for the row-track unit (px) the polyfill uses for `grid-auto-rows` and as the ceil() granularity of each item's row span. Omit to let the polyfill auto-pick the smallest unit that keeps the implicit row count under any browser cap. |
 
 ## Slots
 
@@ -75,7 +76,7 @@ Numeric `column-span="n"` is literal — it does not adapt. Use named values for
 
 ## Nesting
 
-Grids can nest. A `variant="page"` inside another grid uses `grid-column: 1 / -1` so nested page grids always occupy the full width of their container.
+Grids can nest. A `variant="page"` inside another grid uses `grid-column: 1 / -1` so nested page grids always occupy the full width of their container. Because `<bds-grid>` renders its track layout inside a shadow root, the spanning rule is applied to the **host element** itself (`:host([variant='page'])`) rather than the internal `.grid` div — the host is the element that actually participates in the parent grid's tracks.
 
 ```html
 <bds-grid variant="main">
@@ -118,7 +119,9 @@ Targets [CSS Grid Layout Module Level 3](https://www.w3.org/TR/css-grid-3/) ("gr
 - **Native path** — when the browser supports `display: grid-lanes` or `grid-template-rows: masonry`, CSS handles everything and the polyfill short-circuits.
 - **Polyfill path** — row-span packing: the container collapses to a 1 px row track with `grid-auto-flow: dense`, and each item is given `grid-row-end: span ceil(height + gap)`. Items stay in **normal flow** (no absolute positioning), so surrounding content lays out correctly around the grid.
 
-Re-runs on child size changes (`ResizeObserver` on each child) and child addition/removal (`MutationObserver` on the host). The container itself is not observed to avoid a feedback loop — setting row-spans changes the container's block-size.
+Re-runs on child size changes (`ResizeObserver` on each child, and on any `<img>`/`<video>` descendant so late-decoding media is caught the same frame) and child addition/removal (`MutationObserver` on the host). The container itself is not observed to avoid a feedback loop — setting row-spans changes the container's block-size.
+
+A `ResizeObserver`-triggered re-run applies immediately, except while the page is actively scrolling — those are deferred until scroll idles (150ms) to avoid a compositor race where the re-pack visibly overlaps already-painted content. `MutationObserver`-triggered runs (new children) and the initial layout are always deferred one frame via `requestAnimationFrame` so the browser lays out new content before it's measured. Masonry re-engages automatically if the element is disconnected and reconnected (e.g. moved in the DOM).
 
 ### Span behavior in masonry
 
@@ -131,6 +134,7 @@ Re-runs on child size changes (`ResizeObserver` on each child) and child additio
 - Initial layout is one measure pass + one write pass (heights are batched to avoid per-item reflows).
 - Re-layout is scheduled via `requestAnimationFrame` so bursts of observer callbacks coalesce into a single run per frame.
 - Row-gap is baked into each item's span, so ceil-rounding only introduces sub-pixel overshoot per item — not visible in practice.
+- Set `masonry-row-unit-px` to override the auto-picked row-track unit if you've confirmed the auto-tuner is wrong for your gallery (see [Attributes](#attributes)).
 
 ### Accessibility
 

package/src/web-components/layout/BdsGrid.stories.tsx

@@ -10,6 +10,7 @@ function BdsGrid({
   isCentered,
   isMasonry,
   masonryPreferredColumnSpan,
+  masonryRowUnitPx,
   children,
 }: {
   variant?: GridVariant;
@@ -17,6 +18,7 @@ function BdsGrid({
   isCentered?: boolean;
   isMasonry?: boolean;
   masonryPreferredColumnSpan?: string;
+  masonryRowUnitPx?: number;
   children?: React.ReactNode;
 }) {
   return React.createElement(
@@ -27,6 +29,7 @@ function BdsGrid({
       'is-centered': isCentered || undefined,
       'is-masonry': isMasonry || undefined,
       'masonry-preferred-column-span': masonryPreferredColumnSpan,
+      'masonry-row-unit-px': masonryRowUnitPx,
     },
     children,
   );
@@ -78,6 +81,7 @@ const meta = {
       control: 'select',
       options: ['full', 'three-quarters', 'two-thirds', 'half', 'one-third', 'one-quarter'],
     },
+    masonryRowUnitPx: { control: 'number' },
   },
 } satisfies Meta<typeof BdsGrid>;
 

package/src/web-components/layout/bds-grid-item.spec.ts

@@ -48,6 +48,27 @@ describe('bds-grid-item', () => {
     cleanup(el);
   });
 
+  it('restores default span after row-span attribute is removed', async () => {
+    const el = (await fixture('<bds-grid-item row-span="2"></bds-grid-item>')) as BdsGridItem;
+    expect(el.style.gridRow).toBe('span 2');
+    el.removeAttribute('row-span');
+    await el.updateComplete;
+    expect(el.style.gridRow).toBe('');
+    cleanup(el);
+  });
+
+  it('restores default full-span column after start-column/end-column are removed', async () => {
+    const el = (await fixture(
+      '<bds-grid-item start-column="2" end-column="5"></bds-grid-item>',
+    )) as BdsGridItem;
+    expect(el.style.gridColumn).toBe('2 / 5');
+    el.removeAttribute('start-column');
+    el.removeAttribute('end-column');
+    await el.updateComplete;
+    expect(el.style.gridColumn).toBe('var(--bds-grid_span-100)');
+    cleanup(el);
+  });
+
   it('renders slotted children', async () => {
     const el = await fixture('<bds-grid-item>cell</bds-grid-item>');
     expect(el.textContent?.trim()).toBe('cell');

package/src/web-components/layout/bds-grid-item.ts

@@ -55,6 +55,16 @@ function resolveSpan(value: Exclude<GridItemSpanValue, 'auto'> | undefined): str
  */
 export class BdsGridItem extends LitElement {
   static styles = css`
+    /* Shadow DOM does not inherit the global box-sizing reset, so set it
+       here; otherwise elements with an explicit size + padding size as
+       content-box and layouts drift from the React (light-DOM) versions. */
+    :host,
+    *,
+    *::before,
+    *::after {
+      box-sizing: border-box;
+    }
+
     :host {
       display: block;
       min-inline-size: 0;
@@ -151,8 +161,12 @@ export class BdsGridItem extends LitElement {
     const effective = this._effectiveColumnSpan();
     if (effective === 'auto') this._resolveAutoSpan();
 
-    const hasExplicitRange =
-      this.startColumn !== undefined || this.endColumn !== undefined;
+    // Lit's default `Number` attribute converter resolves a removed attribute
+    // to `null` (not `undefined`), so these checks must use `!= null` — an
+    // `!== undefined` check would keep treating a removed attribute as "set"
+    // and produce `span null` / a stuck explicit range instead of restoring
+    // the default span behaviour.
+    const hasExplicitRange = this.startColumn != null || this.endColumn != null;
 
     const resolved = effective === 'auto' ? this._autoSpan : effective;
     const gridColumn = hasExplicitRange
@@ -160,7 +174,7 @@ export class BdsGridItem extends LitElement {
       : resolveSpan(resolved);
 
     this.style.gridColumn = gridColumn;
-    this.style.gridRow = this.rowSpan !== undefined ? `span ${this.rowSpan}` : '';
+    this.style.gridRow = this.rowSpan != null ? `span ${this.rowSpan}` : '';
 
     // Marker the masonry polyfill reads to know this item's span wasn't set by
     // the consumer — it may override with the parent `masonry-preferred-column-span`.

package/src/web-components/layout/bds-grid.spec.ts

@@ -1,7 +1,17 @@
 import { fixture, cleanup } from '../test/helpers';
 import { BdsGrid } from './bds-grid';
+import type { BdsGridItem } from './bds-grid-item';
+// Side-effect import: registers the `bds-grid-item` custom element. BdsGridItem
+// above is used only as a type, which esbuild's isolatedModules-style transform
+// would otherwise elide — silently leaving <bds-grid-item> un-upgraded (a plain
+// HTMLElement) in every fixture in this file that nests one inside <bds-grid>.
 import './bds-grid-item';
 
+/** Flush one requestAnimationFrame tick — the masonry polyfill's schedule/apply cycle. */
+function nextFrame(): Promise<void> {
+  return new Promise((resolve) => requestAnimationFrame(() => resolve()));
+}
+
 describe('bds-grid', () => {
   it('is registered as a custom element', () => {
     expect(customElements.get('bds-grid')).toBe(BdsGrid);
@@ -67,4 +77,92 @@ describe('bds-grid', () => {
     expect(el.masonryPreferredColumnSpan).toBe('half');
     cleanup(el);
   });
+
+  it('reflects masonry-row-unit-px as a number property', async () => {
+    const el = await fixture(
+      '<bds-grid is-masonry masonry-row-unit-px="8"></bds-grid>',
+    ) as BdsGrid;
+    expect(el.masonryRowUnitPx).toBe(8);
+    cleanup(el);
+  });
+
+  it('applies grid-column: 1 / -1 to the host (not the inner .grid) for variant="page", so nested page grids span the parent', () => {
+    const cssText = BdsGrid.styles.cssText;
+    expect(cssText).toMatch(/:host\(\[variant='page'\]\)\s*{[^}]*grid-column:\s*1\s*\/\s*-1/);
+    // The inner .grid.--page rule must not also carry grid-column — the host
+    // (which participates in a parent grid's tracks) owns spanning; the inner
+    // div only owns its own track sizing.
+    expect(cssText).not.toMatch(/\.grid\.--page\s*{[^}]*grid-column:/);
+  });
+
+  it('falls back to the --grid_columns default when the columns attribute is removed', async () => {
+    const el = await fixture(
+      '<bds-grid variant="custom" columns="6"></bds-grid>',
+    ) as BdsGrid;
+    const grid = el.shadowRoot!.querySelector('.grid') as HTMLElement;
+    expect(grid.getAttribute('style')).toContain('--grid_columns: 6');
+
+    el.removeAttribute('columns');
+    await el.updateComplete;
+
+    // Lit's Number converter yields `null` (not `undefined`) when a reflected
+    // attribute is removed. A strict `!== undefined` check would still match
+    // and emit the literal string "null", making `var(--grid_columns, 4)`
+    // resolve to an invalid custom property and collapse the grid to one
+    // column instead of falling back to the default.
+    expect(grid.getAttribute('style') ?? '').not.toContain('null');
+    cleanup(el);
+  });
+
+  it('does not clear a slotted grid-item row-span style when re-rendering a non-masonry grid', async () => {
+    const el = await fixture(
+      '<bds-grid><bds-grid-item row-span="3">A</bds-grid-item></bds-grid>',
+    ) as BdsGrid;
+    const item = el.querySelector('bds-grid-item') as BdsGridItem;
+    await item.updateComplete;
+    expect(item.style.gridRow).toBe('span 3');
+
+    // An unrelated property change re-renders bds-grid. Before the fix,
+    // updated() called clearMasonryLayout() unconditionally on every
+    // non-masonry update, wiping the row-span this GridItem's own render set.
+    el.isCentered = true;
+    await el.updateComplete;
+
+    expect(item.style.gridRow).toBe('span 3');
+    cleanup(el);
+  });
+
+  it('applies a masonry row-span to slotted items after mount', async () => {
+    const el = await fixture(
+      '<bds-grid is-masonry><bds-grid-item>A</bds-grid-item></bds-grid>',
+    ) as BdsGrid;
+    await nextFrame();
+    const item = el.querySelector('bds-grid-item') as HTMLElement;
+    // jsdom reports offsetHeight 0 for unlaid-out elements, so the polyfill
+    // assigns the 1-row floor.
+    expect(item.style.gridRowEnd).toBe('span 1');
+    cleanup(el);
+  });
+
+  it('re-engages masonry after being disconnected and reconnected', async () => {
+    const el = await fixture(
+      '<bds-grid is-masonry><bds-grid-item>A</bds-grid-item></bds-grid>',
+    ) as BdsGrid;
+    await nextFrame();
+    const item = el.querySelector('bds-grid-item') as HTMLElement;
+    expect(item.style.gridRowEnd).toBe('span 1');
+
+    const parent = el.parentElement!;
+    el.remove();
+    // disconnectedCallback tears down masonry synchronously.
+    expect(item.style.gridRowEnd).toBe('');
+
+    parent.appendChild(el);
+    // No property changed, so updated() won't fire — connectedCallback must
+    // re-arm masonry on its own for this to re-apply.
+    await nextFrame();
+    expect(item.style.gridRowEnd).toBe('span 1');
+
+    cleanup(el);
+  });
 });