@boostdev/design-system-components 2.2.1 → 2.4.0

package/src/components/layout/Grid/masonry.ts

@@ -1,4 +1,43 @@
 import { RefObject, useLayoutEffect } from 'react';
+import type { GridItemSpanValue } from './GridItem';
+
+type NamedSpan = Exclude<GridItemSpanValue, 'auto' | number>;
+
+// Named spans resolve through the foundation's responsive column tokens so they
+// match the behavior of `columnSpan` on `GridItem`. The polyfill reads the live
+// value at each run, which is how a single `preferredColumnSpan: 'half'` gives
+// 2 cols on a 4-col mobile grid and 6 cols on a 12-col desktop grid.
+const NAMED_SPAN_VAR: Record<Exclude<NamedSpan, 'full'>, string> = {
+  'three-quarters': '--bds-grid_columns-75',
+  'two-thirds': '--bds-grid_columns-66',
+  half: '--bds-grid_columns-50',
+  'one-third': '--bds-grid_columns-33',
+  'one-quarter': '--bds-grid_columns-25',
+};
+
+// Mathematical fallback for environments where the foundation CSS isn't loaded
+// (e.g. jsdom tests). Round to the nearest integer; clamp to [1, totalCols].
+const NAMED_SPAN_FRACTION: Record<Exclude<NamedSpan, 'full'>, number> = {
+  'three-quarters': 0.75,
+  'two-thirds': 2 / 3,
+  half: 0.5,
+  'one-third': 1 / 3,
+  'one-quarter': 0.25,
+};
+
+function resolvePreferredColumns(
+  container: HTMLElement,
+  value: Exclude<GridItemSpanValue, 'auto'>,
+  totalCols: number,
+): number {
+  if (value === 'full') return totalCols;
+  if (typeof value === 'number') return Math.max(1, Math.min(totalCols, value));
+  const varName = NAMED_SPAN_VAR[value];
+  const raw = window.getComputedStyle(container).getPropertyValue(varName).trim();
+  const n = parseInt(raw, 10);
+  if (Number.isFinite(n) && n > 0) return Math.min(totalCols, n);
+  return Math.max(1, Math.round(totalCols * NAMED_SPAN_FRACTION[value]));
+}
 
 /**
  * Masonry layout polyfill based on CSS Grid Layout Module Level 3 (a.k.a. "grid-lanes").
@@ -36,7 +75,31 @@ export function supportsNativeMasonry(): boolean {
   );
 }
 
-export function applyMasonryLayout(container: HTMLElement, rawChildren: HTMLElement[]): void {
+export type MasonryOptions = {
+  /**
+   * When set, the polyfill assigns column spans to items marked
+   * `data-column-span-auto`. Named values (`'half'`, `'one-third'`, etc.) are
+   * resolved through the foundation's responsive column tokens so the same
+   * option yields the right span at every breakpoint. A `number` is a literal
+   * column count. If a preferred-span item would overflow the row, it is
+   * demoted to fill only the remaining columns (never less than 1). Items with
+   * an explicit `columnSpan` keep their span; their span still consumes column
+   * budget for the demotion calculation.
+   */
+  preferredColumnSpan?: Exclude<GridItemSpanValue, 'auto'>;
+};
+
+// Data attribute used to remember an auto item's inline `grid-column` before the
+// polyfill overwrites it — restored on cleanup or when the preferred option is
+// unset, so a Storybook control going from preferred=2 → undefined doesn't leave
+// items pinned to their polyfill-assigned span.
+const ORIGINAL_COL_ATTR = 'data-bds-masonry-original-column';
+
+export function applyMasonryLayout(
+  container: HTMLElement,
+  rawChildren: HTMLElement[],
+  options: MasonryOptions = {},
+): void {
   // We override row-gap to 0, so reading it back would always give 0 on re-runs.
   // Read column-gap instead — `.grid` sets both via the `gap` shorthand and the
   // polyfill never touches column-gap. (If a consumer sets asymmetric gaps, the
@@ -47,6 +110,13 @@ export function applyMasonryLayout(container: HTMLElement, rawChildren: HTMLElem
   container.style.gridAutoRows = `${ROW_UNIT_PX}px`;
   container.style.rowGap = '0px';
   container.style.gridAutoFlow = 'dense';
+  // `dense` + per-child `ResizeObserver` can fight the browser's scroll anchoring:
+  // a subpixel child resize (scrollbar toggling, late image decode, font swap) re-runs
+  // the pack, items above the viewport shift, and the browser yanks the viewport up
+  // to "follow" them. Opting this container out of scroll anchoring means the browser
+  // picks something outside the grid as the anchor, so internal reshuffles are invisible
+  // to scroll position. Cleared in clearMasonryLayout.
+  container.style.overflowAnchor = 'none';
 
   const children = rawChildren.filter(
     (el) => el.nodeType === 1 && window.getComputedStyle(el).display !== 'none',
@@ -63,6 +133,41 @@ export function applyMasonryLayout(container: HTMLElement, rawChildren: HTMLElem
     child.style.alignSelf = 'start';
   }
 
+  // Preferred-column-span pass — optional. Assigns column spans to `data-column-span-auto`
+  // items, demoting to fit remaining row space. Runs before height measurement so items
+  // are measured at the width they will actually render. When the option is not set,
+  // any previously-written spans are restored to their original inline value so
+  // a Storybook control change from preferred='half' → undefined doesn't leave auto
+  // items pinned.
+  const preferred = options.preferredColumnSpan;
+  if (preferred !== undefined) {
+    const totalCols = countGridColumns(container);
+    const preferredCols = totalCols > 0 ? resolvePreferredColumns(container, preferred, totalCols) : 0;
+    if (totalCols > 0 && preferredCols > 0) {
+      let col = 0;
+      for (const child of children) {
+        if (child.hasAttribute('data-column-span-auto')) {
+          if (!child.hasAttribute(ORIGINAL_COL_ATTR)) {
+            child.setAttribute(ORIGINAL_COL_ATTR, child.style.gridColumn);
+          }
+          const remaining = totalCols - col;
+          const span = Math.max(1, Math.min(preferredCols, remaining));
+          child.style.gridColumn = `span ${span}`;
+          col = (col + span) % totalCols;
+        } else {
+          // Item has an explicit span — consume its columns for the demotion budget.
+          const consumed = Math.min(totalCols, readExplicitSpan(child, totalCols));
+          col = (col + consumed) % totalCols;
+        }
+      }
+    }
+  } else {
+    // No preferred span — restore any items the polyfill previously wrote.
+    for (const child of children) {
+      restoreOriginalColumn(child);
+    }
+  }
+
   // Pass 2 — read all heights in a tight loop. The first offsetHeight read forces one
   // reflow; subsequent reads are cached until the next style write. This avoids the
   // O(N) forced-reflow cost of a read-then-write loop.
@@ -76,25 +181,70 @@ export function applyMasonryLayout(container: HTMLElement, rawChildren: HTMLElem
   }
 }
 
+function countGridColumns(container: HTMLElement): number {
+  // `getComputedStyle` resolves `grid-template-columns` to concrete track sizes
+  // (e.g. "256px 256px 256px 256px"), regardless of whether the author used
+  // `repeat()`, `minmax()`, or CSS custom properties. Splitting by whitespace
+  // gives the actual track count at the current viewport width.
+  const value = window.getComputedStyle(container).gridTemplateColumns.trim();
+  if (!value || value === 'none') return 0;
+  return value.split(/\s+/).length;
+}
+
+function readExplicitSpan(el: HTMLElement, totalCols: number): number {
+  // Try the inline value first to avoid resolving CSS vars that haven't been
+  // registered with `@property` (computed style returns the literal string for
+  // those). Inline values look like `span N`, `span var(...)`, or `a / b`.
+  const inline = el.style.gridColumn || el.style.gridColumnEnd;
+  const fromInline = parseSpan(inline, totalCols);
+  if (fromInline !== null) return fromInline;
+  const computed = window.getComputedStyle(el).gridColumn;
+  return parseSpan(computed, totalCols) ?? 1;
+}
+
+function parseSpan(value: string, totalCols: number): number | null {
+  if (!value) return null;
+  const match = value.match(/^\s*span\s+(\d+)/);
+  if (match) return Math.max(1, Math.min(totalCols, parseInt(match[1], 10)));
+  // `1 / -1` style — spans the whole row.
+  if (/\/\s*-1\b/.test(value)) return totalCols;
+  return null;
+}
+
 export function clearMasonryLayout(container: HTMLElement, rawChildren: HTMLElement[]): void {
   container.style.gridAutoRows = '';
   container.style.gridAutoFlow = '';
   container.style.rowGap = '';
+  container.style.overflowAnchor = '';
   for (const child of rawChildren) {
     if (child.nodeType !== 1) continue;
     child.style.gridRow = '';
     child.style.gridRowStart = '';
     child.style.gridRowEnd = '';
     child.style.alignSelf = '';
+    // Restore any `gridColumn` value the polyfill overwrote. Items the
+    // polyfill never touched have no ORIGINAL_COL_ATTR and are left alone.
+    restoreOriginalColumn(child);
   }
 }
 
+function restoreOriginalColumn(el: HTMLElement): void {
+  if (!el.hasAttribute(ORIGINAL_COL_ATTR)) return;
+  el.style.gridColumn = el.getAttribute(ORIGINAL_COL_ATTR) ?? '';
+  el.removeAttribute(ORIGINAL_COL_ATTR);
+}
+
 /**
  * React hook that runs the polyfill against `ref.current` and re-runs on
  * size / mutation changes. No-op when `enabled` is false or when the browser
  * natively supports masonry.
  */
-export function useMasonry(ref: RefObject<HTMLElement | null>, enabled: boolean): void {
+export function useMasonry(
+  ref: RefObject<HTMLElement | null>,
+  enabled: boolean,
+  options: MasonryOptions = {},
+): void {
+  const { preferredColumnSpan } = options;
   useLayoutEffect(() => {
     const container = ref.current;
     if (!container || !enabled) return;
@@ -104,7 +254,9 @@ export function useMasonry(ref: RefObject<HTMLElement | null>, enabled: boolean)
     const schedule = () => {
       cancelAnimationFrame(frame);
       frame = requestAnimationFrame(() => {
-        applyMasonryLayout(container, Array.from(container.children) as HTMLElement[]);
+        applyMasonryLayout(container, Array.from(container.children) as HTMLElement[], {
+          preferredColumnSpan,
+        });
       });
     };
 
@@ -135,5 +287,5 @@ export function useMasonry(ref: RefObject<HTMLElement | null>, enabled: boolean)
       mo?.disconnect();
       clearMasonryLayout(container, Array.from(container.children) as HTMLElement[]);
     };
-  }, [ref, enabled]);
+  }, [ref, enabled, preferredColumnSpan]);
 }

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

@@ -49,6 +49,7 @@ Numeric `column-span="n"` is literal — it does not adapt. Use named values for
 | `is-centered`     | boolean                                        | `false`  | Caps max-width via `--bds-container_max-width`     |
 | `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). |
 
 ## Slots
 
@@ -161,6 +162,41 @@ Individual items can opt out with an explicit `column-span` (e.g. `column-span="
 
 Named-span responsive behavior still applies — on mobile every item collapses to full-width regardless of its resolved span.
 
+## Masonry preferred column span
+
+For a uniform "cards mostly half-width" feed, set `masonry-preferred-column-span` on the `<bds-grid>`. Items without an explicit `column-span` try to span that named fraction of the row. When an item would sit at the end of a row with fewer columns remaining than the preferred span, the polyfill **demotes** its span to just fill the remaining columns — the item never wraps to a new row leaving a visible gap behind it.
+
+```html
+<bds-grid is-masonry masonry-preferred-column-span="half">
+  <bds-grid-item>…</bds-grid-item>
+  <bds-grid-item>…</bds-grid-item>
+</bds-grid>
+```
+
+Accepted values match `column-span` on `<bds-grid-item>`: `"full"`, `"three-quarters"`, `"two-thirds"`, `"half"`, `"one-third"`, `"one-quarter"`. Named values resolve through the foundation's responsive column tokens, so the same option adapts across breakpoints — `"half"` yields 2 cols on a 4-col mobile grid, 4 cols on an 8-col tablet grid, and 6 cols on a 12-col desktop grid. A numeric string (e.g. `"2"`) is accepted too, but is a literal column count and does **not** adapt — prefer named values unless you're using `variant="custom"`.
+
+Rules:
+
+- Requires `is-masonry`. No-op on non-masonry grids.
+- Items with an explicit `column-span` (named or numeric) keep their span. Their columns still consume the demotion budget, so a `column-span="three-quarters"` followed by an auto item in a 4-column grid correctly demotes the auto item to 1.
+- Items with `start-column` / `end-column` are unaffected.
+- Responsive: the polyfill reads the live column count at the current viewport width, so the same grid can be 2+2 on wide screens and 1+1+1+1 on mobile without any media-query wiring.
+
+### When NOT to use
+
+- When span should reflect **content importance** or media shape — set `column-span` per item instead. `masonry-preferred-column-span` enforces a uniform visual rhythm and is the wrong tool for heterogeneous cards.
+- Alongside `auto-span-media` on the same grid. Both features target items without an explicit `column-span`, and `masonry-preferred-column-span` wins — `auto-span-media` silently does nothing. Pick one strategy per grid.
+- In a non-masonry grid. The feature depends on the polyfill's packing pass and is a no-op otherwise — use a plain `column-span` default instead.
+
+### Performance
+
+- One extra `getComputedStyle(container).gridTemplateColumns` read per masonry layout pass to count columns; the demotion pass itself is a single O(n) walk over auto items.
+- Shares the polyfill's existing `ResizeObserver` + `MutationObserver` + `requestAnimationFrame` coalescing — no new observers, no separate render.
+
+### SSR / hydration
+
+Column detection runs inside the masonry polyfill's layout pass after upgrade, so it only executes on the client. The initial server render emits each auto item at its default `full` span until the custom element upgrades and the first polyfill pass runs — matching the existing masonry SSR behavior.
+
 ### Loading behavior
 
 Dimensions are read from `img.naturalWidth/naturalHeight` and `video.videoWidth/videoHeight` — no layout is triggered. If metadata is not yet available when the element upgrades, the item starts at `'one-quarter'` and re-resolves when the `load` (image) or `loadedmetadata` (video) event fires. Subsequent slot mutations re-run the resolver.

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

@@ -9,12 +9,14 @@ function BdsGrid({
   columns,
   isCentered,
   isMasonry,
+  masonryPreferredColumnSpan,
   children,
 }: {
   variant?: GridVariant;
   columns?: number;
   isCentered?: boolean;
   isMasonry?: boolean;
+  masonryPreferredColumnSpan?: string;
   children?: React.ReactNode;
 }) {
   return React.createElement(
@@ -24,6 +26,7 @@ function BdsGrid({
       columns,
       'is-centered': isCentered || undefined,
       'is-masonry': isMasonry || undefined,
+      'masonry-preferred-column-span': masonryPreferredColumnSpan,
     },
     children,
   );
@@ -45,7 +48,7 @@ function Item({
   return React.createElement(
     'bds-grid-item',
     {
-      'column-span': columnSpan ?? 'full',
+      'column-span': columnSpan,
       'start-column': startColumn,
       'end-column': endColumn,
       'row-span': rowSpan,
@@ -71,6 +74,10 @@ const meta = {
     columns: { control: 'number' },
     isCentered: { control: 'boolean' },
     isMasonry: { control: 'boolean' },
+    masonryPreferredColumnSpan: {
+      control: 'select',
+      options: ['full', 'three-quarters', 'two-thirds', 'half', 'one-third', 'one-quarter'],
+    },
   },
 } satisfies Meta<typeof BdsGrid>;
 
@@ -189,6 +196,46 @@ export const MasonryWithSpans: Story = {
   ),
 };
 
+/**
+ * `masonry-preferred-column-span="half"` makes every auto-span item try to
+ * span half the grid. Named values resolve through the foundation's responsive
+ * column tokens, so the same value yields 2 cols on a 4-col mobile grid, 4 on
+ * an 8-col tablet grid, and 6 on a 12-col desktop grid.
+ *
+ * When an item would overflow the row, the polyfill **demotes** its span to
+ * fill just the remaining columns, so no trailing gap appears.
+ *
+ * Swap `masonryPreferredColumnSpan` between named values in the Controls and
+ * resize the viewport to watch the demotion adapt to the current column count.
+ */
+export const MasonryPreferredColumnSpan: Story = {
+  args: { isMasonry: true, masonryPreferredColumnSpan: 'half' },
+  render: (args) => (
+    <BdsGrid {...args}>
+      {Array.from({ length: 7 }).map((_, i) => (
+        <Item key={i}><div style={masonryCellStyle(i)}>Card {i + 1}</div></Item>
+      ))}
+    </BdsGrid>
+  ),
+};
+
+/**
+ * An explicit `column-span="three-quarters"` hero alongside auto items.
+ * The hero keeps its span; its columns consume the demotion budget, so the
+ * auto items fill the remaining row consistently.
+ */
+export const MasonryPreferredColumnSpanWithHero: Story = {
+  args: { isMasonry: true, masonryPreferredColumnSpan: 'half' },
+  render: (args) => (
+    <BdsGrid {...args}>
+      <Item columnSpan="three-quarters"><div style={masonryCellStyle(0)}>Hero (three-quarters)</div></Item>
+      {Array.from({ length: 8 }).map((_, i) => (
+        <Item key={i}><div style={masonryCellStyle(i + 1)}>Card {i + 1}</div></Item>
+      ))}
+    </BdsGrid>
+  ),
+};
+
 export const ComplexLayout: Story = {
   args: {},
   render: () => (

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

@@ -99,4 +99,18 @@ describe('bds-grid-item', () => {
     expect(item.style.gridColumn).toBe('span var(--bds-grid_columns-33)');
     cleanup(grid);
   });
+
+  it('marks data-column-span-auto when column-span is not set', async () => {
+    const el = (await fixture('<bds-grid-item></bds-grid-item>')) as BdsGridItem;
+    expect(el.hasAttribute('data-column-span-auto')).toBe(true);
+    cleanup(el);
+  });
+
+  it('clears data-column-span-auto when column-span is set', async () => {
+    const el = (await fixture(
+      '<bds-grid-item column-span="half"></bds-grid-item>',
+    )) as BdsGridItem;
+    expect(el.hasAttribute('data-column-span-auto')).toBe(false);
+    cleanup(el);
+  });
 });

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

@@ -161,6 +161,13 @@ export class BdsGridItem extends LitElement {
 
     this.style.gridColumn = gridColumn;
     this.style.gridRow = this.rowSpan !== undefined ? `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`.
+    const isColumnSpanAuto =
+      (this.columnSpan === undefined || this.columnSpan === null) && !hasExplicitRange;
+    if (isColumnSpanAuto) this.setAttribute('data-column-span-auto', '');
+    else this.removeAttribute('data-column-span-auto');
   }
 
   render() {

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

@@ -59,4 +59,12 @@ describe('bds-grid', () => {
     expect(el.shadowRoot!.querySelector('.grid')!.classList.contains('--masonry')).toBe(true);
     cleanup(el);
   });
+
+  it('reflects masonry-preferred-column-span as a string property', async () => {
+    const el = await fixture(
+      '<bds-grid is-masonry masonry-preferred-column-span="half"></bds-grid>',
+    ) as BdsGrid;
+    expect(el.masonryPreferredColumnSpan).toBe('half');
+    cleanup(el);
+  });
 });

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

@@ -1,5 +1,6 @@
 import { LitElement, css, html } from 'lit';
 import { applyMasonryLayout, clearMasonryLayout, supportsNativeMasonry } from '../../components/layout/Grid/masonry';
+import type { GridItemSpanValue } from '../../components/layout/Grid/GridItem';
 
 export type GridVariant = 'main' | 'page' | 'funnel' | 'custom';
 
@@ -16,6 +17,12 @@ export type GridVariant = 'main' | 'page' | 'funnel' | 'custom';
  *   auto-span-media — boolean; child `<bds-grid-item>`s without a `column-span`
  *                     attribute resolve their span from the intrinsic aspect
  *                     ratio of their first `<img>`/`<video>` child.
+ *   masonry-preferred-column-span — named span or number; masonry only. Child
+ *                     items without a `column-span` attribute try to span this
+ *                     value (e.g. `"half"`, `"one-third"`). Named values adapt
+ *                     across breakpoints via the foundation's responsive column
+ *                     tokens. An item at row-end is demoted to the remaining
+ *                     column count. Numeric values are literal and don't adapt.
  *
  * Slots:
  *   (default) — grid content; typically `<bds-grid-item>` children
@@ -76,6 +83,11 @@ export class BdsGrid extends LitElement {
     isCentered: { type: Boolean, attribute: 'is-centered', reflect: true },
     isMasonry: { type: Boolean, attribute: 'is-masonry', reflect: true },
     autoSpanMedia: { type: Boolean, attribute: 'auto-span-media', reflect: true },
+    masonryPreferredColumnSpan: {
+      type: String,
+      attribute: 'masonry-preferred-column-span',
+      reflect: true,
+    },
   };
 
   declare variant: GridVariant;
@@ -83,6 +95,7 @@ export class BdsGrid extends LitElement {
   declare isCentered: boolean;
   declare isMasonry: boolean;
   declare autoSpanMedia: boolean;
+  declare masonryPreferredColumnSpan: string | undefined;
 
   private _ro?: ResizeObserver;
   private _mo?: MutationObserver;
@@ -95,6 +108,7 @@ export class BdsGrid extends LitElement {
     this.isCentered = false;
     this.isMasonry = false;
     this.autoSpanMedia = false;
+    this.masonryPreferredColumnSpan = undefined;
   }
 
   disconnectedCallback() {
@@ -144,10 +158,23 @@ export class BdsGrid extends LitElement {
     cancelAnimationFrame(this._frame);
     this._frame = requestAnimationFrame(() => {
       const container = this._gridEl();
-      if (container) applyMasonryLayout(container, this._items());
+      if (container) {
+        applyMasonryLayout(container, this._items(), {
+          preferredColumnSpan: this._resolvePreferredColumnSpan(),
+        });
+      }
     });
   }
 
+  private _resolvePreferredColumnSpan(): Exclude<GridItemSpanValue, 'auto'> | undefined {
+    const raw = this.masonryPreferredColumnSpan;
+    if (raw === undefined || raw === null || raw === '') return undefined;
+    // Numeric attribute → literal column count; otherwise treat as a named span.
+    const n = Number(raw);
+    if (Number.isFinite(n) && String(n) === raw) return n;
+    return raw as Exclude<GridItemSpanValue, 'auto'>;
+  }
+
   private _teardownMasonry() {
     cancelAnimationFrame(this._frame);
     this._ro?.disconnect();