@boostdev/design-system-components 2.1.0 → 2.2.1

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

@@ -0,0 +1,184 @@
+import { LitElement, css, html } from 'lit';
+import { applyMasonryLayout, clearMasonryLayout, supportsNativeMasonry } from '../../components/layout/Grid/masonry';
+
+export type GridVariant = 'main' | 'page' | 'funnel' | 'custom';
+
+/**
+ * `<bds-grid>` — framework-agnostic Grid layout custom element.
+ *
+ * Attributes:
+ *   variant     — "main" (default) | "page" | "funnel" | "custom"
+ *   columns     — number; column count when variant="custom"
+ *   is-centered — boolean; centers the grid and caps width via --bds-container_max-width
+ *   is-masonry  — boolean; enables masonry layout per CSS Grid Level 3.
+ *                 Uses native `display: grid-lanes` / `grid-template-rows: masonry`
+ *                 when supported, otherwise runs a JS polyfill.
+ *   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.
+ *
+ * Slots:
+ *   (default) — grid content; typically `<bds-grid-item>` children
+ */
+export class BdsGrid extends LitElement {
+  static styles = css`
+    :host {
+      display: block;
+    }
+
+    .grid {
+      display: grid;
+      gap: var(--grid_gap, var(--bds-grid_gap));
+      box-sizing: border-box;
+    }
+
+    .grid.--main {
+      grid-template-columns: var(--bds-grid_template-columns);
+    }
+
+    .grid.--page {
+      grid-template-columns: 1fr;
+      grid-column: 1 / -1;
+    }
+
+    .grid.--funnel {
+      grid-template-columns: var(--bds-grid_template-columns);
+      max-inline-size: var(--bds-container_max-width--narrow);
+      margin-inline: auto;
+    }
+
+    .grid.--custom {
+      grid-template-columns: repeat(var(--grid_columns, 4), minmax(0, 1fr));
+    }
+
+    .grid.--centered {
+      margin-inline: auto;
+      max-inline-size: var(--bds-container_max-width);
+      padding-inline: var(--bds-container_spacing-inline);
+    }
+
+    @supports (grid-template-rows: masonry) {
+      .grid.--masonry {
+        grid-template-rows: masonry;
+      }
+    }
+
+    @supports (display: grid-lanes) {
+      .grid.--masonry {
+        display: grid-lanes;
+      }
+    }
+  `;
+
+  static properties = {
+    variant: { type: String, reflect: true },
+    columns: { type: Number, reflect: true },
+    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 },
+  };
+
+  declare variant: GridVariant;
+  declare columns: number | undefined;
+  declare isCentered: boolean;
+  declare isMasonry: boolean;
+  declare autoSpanMedia: boolean;
+
+  private _ro?: ResizeObserver;
+  private _mo?: MutationObserver;
+  private _frame = 0;
+
+  constructor() {
+    super();
+    this.variant = 'main';
+    this.columns = undefined;
+    this.isCentered = false;
+    this.isMasonry = false;
+    this.autoSpanMedia = false;
+  }
+
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    this._teardownMasonry();
+  }
+
+  updated() {
+    if (this.isMasonry && !supportsNativeMasonry()) {
+      this._setupMasonry();
+      this._scheduleMasonry();
+    } else {
+      this._teardownMasonry();
+    }
+  }
+
+  private _gridEl(): HTMLElement | null {
+    return this.renderRoot.querySelector<HTMLElement>('.grid');
+  }
+
+  private _items(): HTMLElement[] {
+    return (Array.from(this.children) as HTMLElement[]).filter((el) => el.nodeType === 1);
+  }
+
+  private _setupMasonry() {
+    if (this._ro || this._mo) return;
+    const container = this._gridEl();
+    if (!container) return;
+
+    if (typeof ResizeObserver !== 'undefined') {
+      this._ro = new ResizeObserver(() => this._scheduleMasonry());
+      // Only observe children, not the container — container block-size changes when
+      // we apply row-spans, which would loop back through the observer.
+      for (const child of this._items()) this._ro.observe(child);
+    }
+
+    if (typeof MutationObserver !== 'undefined') {
+      this._mo = new MutationObserver(() => {
+        if (this._ro) for (const child of this._items()) this._ro.observe(child);
+        this._scheduleMasonry();
+      });
+      this._mo.observe(this, { childList: true });
+    }
+  }
+
+  private _scheduleMasonry() {
+    cancelAnimationFrame(this._frame);
+    this._frame = requestAnimationFrame(() => {
+      const container = this._gridEl();
+      if (container) applyMasonryLayout(container, this._items());
+    });
+  }
+
+  private _teardownMasonry() {
+    cancelAnimationFrame(this._frame);
+    this._ro?.disconnect();
+    this._mo?.disconnect();
+    this._ro = undefined;
+    this._mo = undefined;
+    const container = this._gridEl();
+    if (container) clearMasonryLayout(container, this._items());
+  }
+
+  render() {
+    const classes = [
+      'grid',
+      `--${this.variant}`,
+      this.isCentered ? '--centered' : '',
+      this.isMasonry ? '--masonry' : '',
+    ].filter(Boolean).join(' ');
+
+    const styleAttr =
+      this.variant === 'custom' && this.columns !== undefined
+        ? `--grid_columns: ${this.columns}`
+        : '';
+
+    return html`<div class=${classes} style=${styleAttr}><slot></slot></div>`;
+  }
+}
+
+customElements.define('bds-grid', BdsGrid);
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'bds-grid': BdsGrid;
+  }
+}