@boostdev/design-system-components 2.2.0 → 2.3.0

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?: number;
   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,7 @@ const meta = {
     columns: { control: 'number' },
     isCentered: { control: 'boolean' },
     isMasonry: { control: 'boolean' },
+    masonryPreferredColumnSpan: { control: { type: 'number', min: 1, max: 4 } },
   },
 } satisfies Meta<typeof BdsGrid>;
 
@@ -189,6 +193,43 @@ export const MasonryWithSpans: Story = {
   ),
 };
 
+/**
+ * `masonry-preferred-column-span="2"` makes every auto-span item span 2 columns.
+ * With 7 items in a 12-column desktop grid, the 7th would normally leave a trailing
+ * gap — the polyfill **demotes** its span to fill just the remaining columns.
+ *
+ * Flip `masonryPreferredColumnSpan` between 1–4 in the Controls to see the
+ * packing re-run. Resize the viewport to watch the demotion adapt to the
+ * current column count.
+ */
+export const MasonryPreferredColumnSpan: Story = {
+  args: { isMasonry: true, masonryPreferredColumnSpan: 2 },
+  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: 2 },
+  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 number property', async () => {
+    const el = await fixture(
+      '<bds-grid is-masonry masonry-preferred-column-span="2"></bds-grid>',
+    ) as BdsGrid;
+    expect(el.masonryPreferredColumnSpan).toBe(2);
+    cleanup(el);
+  });
 });

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

@@ -16,6 +16,9 @@ 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 — number; masonry only. Child items without a
+ *                     `column-span` attribute try to span this many columns; an
+ *                     item at row-end is demoted to the remaining column count.
  *
  * Slots:
  *   (default) — grid content; typically `<bds-grid-item>` children
@@ -76,6 +79,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: Number,
+      attribute: 'masonry-preferred-column-span',
+      reflect: true,
+    },
   };
 
   declare variant: GridVariant;
@@ -83,6 +91,7 @@ export class BdsGrid extends LitElement {
   declare isCentered: boolean;
   declare isMasonry: boolean;
   declare autoSpanMedia: boolean;
+  declare masonryPreferredColumnSpan: number | undefined;
 
   private _ro?: ResizeObserver;
   private _mo?: MutationObserver;
@@ -95,6 +104,7 @@ export class BdsGrid extends LitElement {
     this.isCentered = false;
     this.isMasonry = false;
     this.autoSpanMedia = false;
+    this.masonryPreferredColumnSpan = undefined;
   }
 
   disconnectedCallback() {
@@ -144,7 +154,11 @@ 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.masonryPreferredColumnSpan,
+        });
+      }
     });
   }