@boostdev/design-system-components 2.1.0 → 2.2.0

package/dist/web-components/index.d.ts

@@ -41,6 +41,134 @@ export { BdsLink } from './ui/bds-link.js';
 import * as lit from 'lit';
 import { LitElement } from 'lit';
 
+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
+ */
+declare class BdsGrid extends LitElement {
+    static styles: lit.CSSResult;
+    static properties: {
+        variant: {
+            type: StringConstructor;
+            reflect: boolean;
+        };
+        columns: {
+            type: NumberConstructor;
+            reflect: boolean;
+        };
+        isCentered: {
+            type: BooleanConstructor;
+            attribute: string;
+            reflect: boolean;
+        };
+        isMasonry: {
+            type: BooleanConstructor;
+            attribute: string;
+            reflect: boolean;
+        };
+        autoSpanMedia: {
+            type: BooleanConstructor;
+            attribute: string;
+            reflect: boolean;
+        };
+    };
+    variant: GridVariant;
+    columns: number | undefined;
+    isCentered: boolean;
+    isMasonry: boolean;
+    autoSpanMedia: boolean;
+    private _ro?;
+    private _mo?;
+    private _frame;
+    constructor();
+    disconnectedCallback(): void;
+    updated(): void;
+    private _gridEl;
+    private _items;
+    private _setupMasonry;
+    private _scheduleMasonry;
+    private _teardownMasonry;
+    render(): lit.TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'bds-grid': BdsGrid;
+    }
+}
+
+type GridItemSpanValue = 'full' | 'three-quarters' | 'two-thirds' | 'half' | 'one-third' | 'one-quarter' | 'auto' | number;
+/**
+ * `<bds-grid-item>` — grid cell for `<bds-grid>`.
+ *
+ * Attributes:
+ *   column-span   — 'full' | 'three-quarters' | 'two-thirds' | 'half' | 'one-third' | 'one-quarter' | 'auto' | number
+ *                   `'auto'` derives the span from the intrinsic aspect ratio of the first
+ *                   `<img>` or `<video>` child (see Grid.mdx for thresholds).
+ *                   If the parent `<bds-grid>` sets `auto-span-media` and this element has
+ *                   no `column-span`, the item behaves as if `column-span="auto"`.
+ *   row-span      — number
+ *   start-column  — number (escape hatch; overrides column-span)
+ *   end-column    — number (escape hatch; overrides column-span)
+ *
+ * @example
+ * <bds-grid-item column-span="three-quarters">Content</bds-grid-item>
+ */
+declare class BdsGridItem extends LitElement {
+    static styles: lit.CSSResult;
+    static properties: {
+        columnSpan: {
+            attribute: string;
+        };
+        rowSpan: {
+            attribute: string;
+            type: NumberConstructor;
+        };
+        startColumn: {
+            attribute: string;
+            type: NumberConstructor;
+        };
+        endColumn: {
+            attribute: string;
+            type: NumberConstructor;
+        };
+    };
+    columnSpan: GridItemSpanValue | undefined;
+    rowSpan: number | undefined;
+    startColumn: number | undefined;
+    endColumn: number | undefined;
+    private _autoSpan;
+    private _mediaCleanup?;
+    private _slotObserver?;
+    constructor();
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    private _effectiveColumnSpan;
+    private _teardownMedia;
+    private _resolveAutoSpan;
+    private _setAutoSpan;
+    updated(): void;
+    render(): lit.TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'bds-grid-item': BdsGridItem;
+    }
+}
+
 type ButtonGroupOrientation = 'horizontal' | 'vertical';
 /**
  * `<bds-button-group>` — groups related buttons into a flex container.
@@ -608,4 +736,4 @@ declare global {
     }
 }
 
-export { BdsButtonGroup, BdsCalendar, BdsCarousel, BdsCheckboxGroup, BdsDropdownMenu, BdsDropdownMenuItem, BdsFormInput, BdsPagination, BdsRadioGroup, BdsTable };
+export { BdsButtonGroup, BdsCalendar, BdsCarousel, BdsCheckboxGroup, BdsDropdownMenu, BdsDropdownMenuItem, BdsFormInput, BdsGrid, BdsGridItem, BdsPagination, BdsRadioGroup, BdsTable };

package/dist/web-components/index.js

@@ -126,6 +126,315 @@ import {
   i2
 } from "./chunk-LGEZYFUU.js";
 
+// src/components/layout/Grid/masonry.ts
+import { useLayoutEffect } from "react";
+var ROW_UNIT_PX = 1;
+function supportsNativeMasonry() {
+  if (typeof CSS === "undefined" || typeof CSS.supports !== "function") return false;
+  return CSS.supports("display", "grid-lanes") || CSS.supports("grid-template-rows", "masonry");
+}
+function applyMasonryLayout(container, rawChildren) {
+  const cs = window.getComputedStyle(container);
+  const targetGap = parseFloat(cs.columnGap) || 0;
+  container.style.gridAutoRows = `${ROW_UNIT_PX}px`;
+  container.style.rowGap = "0px";
+  container.style.gridAutoFlow = "dense";
+  const children = rawChildren.filter(
+    (el) => el.nodeType === 1 && window.getComputedStyle(el).display !== "none"
+  );
+  for (const child of children) {
+    child.style.gridRow = "";
+    child.style.gridRowStart = "";
+    child.style.gridRowEnd = "";
+  }
+  const heights = children.map((child) => child.offsetHeight);
+  for (let i3 = 0; i3 < children.length; i3++) {
+    const span = Math.max(1, Math.ceil(heights[i3] + targetGap));
+    children[i3].style.gridRowEnd = `span ${span}`;
+  }
+}
+function clearMasonryLayout(container, rawChildren) {
+  container.style.gridAutoRows = "";
+  container.style.gridAutoFlow = "";
+  container.style.rowGap = "";
+  for (const child of rawChildren) {
+    if (child.nodeType !== 1) continue;
+    child.style.gridRow = "";
+    child.style.gridRowStart = "";
+    child.style.gridRowEnd = "";
+  }
+}
+
+// src/web-components/layout/bds-grid.ts
+var BdsGrid = class extends i2 {
+  static styles = i`
+    :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 }
+  };
+  _ro;
+  _mo;
+  _frame = 0;
+  constructor() {
+    super();
+    this.variant = "main";
+    this.columns = void 0;
+    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();
+    }
+  }
+  _gridEl() {
+    return this.renderRoot.querySelector(".grid");
+  }
+  _items() {
+    return Array.from(this.children).filter((el) => el.nodeType === 1);
+  }
+  _setupMasonry() {
+    if (this._ro || this._mo) return;
+    const container = this._gridEl();
+    if (!container) return;
+    if (typeof ResizeObserver !== "undefined") {
+      this._ro = new ResizeObserver(() => this._scheduleMasonry());
+      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 });
+    }
+  }
+  _scheduleMasonry() {
+    cancelAnimationFrame(this._frame);
+    this._frame = requestAnimationFrame(() => {
+      const container = this._gridEl();
+      if (container) applyMasonryLayout(container, this._items());
+    });
+  }
+  _teardownMasonry() {
+    cancelAnimationFrame(this._frame);
+    this._ro?.disconnect();
+    this._mo?.disconnect();
+    this._ro = void 0;
+    this._mo = void 0;
+    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 !== void 0 ? `--grid_columns: ${this.columns}` : "";
+    return T`<div class=${classes} style=${styleAttr}><slot></slot></div>`;
+  }
+};
+customElements.define("bds-grid", BdsGrid);
+
+// src/components/layout/Grid/autoSpan.ts
+function aspectToColumnSpan(ratio) {
+  if (!Number.isFinite(ratio) || ratio <= 0) return "one-quarter";
+  if (ratio > 3.5) return "full";
+  if (ratio > 2.2) return "three-quarters";
+  if (ratio > 1.5) return "half";
+  return "one-quarter";
+}
+function findMediaChild(root) {
+  return root.querySelector("img, video");
+}
+function readMediaAspect(media) {
+  if (media instanceof HTMLImageElement) {
+    if (media.naturalWidth > 0 && media.naturalHeight > 0) {
+      return media.naturalWidth / media.naturalHeight;
+    }
+    return null;
+  }
+  if (media.videoWidth > 0 && media.videoHeight > 0) {
+    return media.videoWidth / media.videoHeight;
+  }
+  return null;
+}
+function mediaReadyEvent(media) {
+  if (media instanceof HTMLImageElement) return media.complete ? null : "load";
+  if (media.readyState < 1) return "loadedmetadata";
+  return null;
+}
+
+// src/web-components/layout/bds-grid-item.ts
+var SPAN_VAR = {
+  full: "var(--bds-grid_span-100)",
+  "three-quarters": "span var(--bds-grid_columns-75)",
+  "two-thirds": "span var(--bds-grid_columns-66)",
+  half: "span var(--bds-grid_columns-50)",
+  "one-third": "span var(--bds-grid_columns-33)",
+  "one-quarter": "span var(--bds-grid_columns-25)"
+};
+function resolveSpan(value) {
+  if (value === void 0 || value === null) return SPAN_VAR.full;
+  if (typeof value === "number") return `span ${value}`;
+  if (!(value in SPAN_VAR)) {
+    const n = Number(value);
+    if (Number.isFinite(n)) return `span ${n}`;
+    return SPAN_VAR.full;
+  }
+  return SPAN_VAR[value];
+}
+var BdsGridItem = class extends i2 {
+  static styles = i`
+    :host {
+      display: block;
+      min-inline-size: 0;
+    }
+  `;
+  static properties = {
+    columnSpan: { attribute: "column-span" },
+    rowSpan: { attribute: "row-span", type: Number },
+    startColumn: { attribute: "start-column", type: Number },
+    endColumn: { attribute: "end-column", type: Number }
+  };
+  _autoSpan = "one-quarter";
+  _mediaCleanup;
+  _slotObserver;
+  constructor() {
+    super();
+    this.columnSpan = void 0;
+    this.rowSpan = void 0;
+    this.startColumn = void 0;
+    this.endColumn = void 0;
+  }
+  connectedCallback() {
+    super.connectedCallback();
+    if (typeof MutationObserver !== "undefined") {
+      this._slotObserver = new MutationObserver(() => this._resolveAutoSpan());
+      this._slotObserver.observe(this, { childList: true, subtree: true });
+    }
+  }
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    this._teardownMedia();
+    this._slotObserver?.disconnect();
+    this._slotObserver = void 0;
+  }
+  _effectiveColumnSpan() {
+    if (this.columnSpan !== void 0 && this.columnSpan !== null) return this.columnSpan;
+    const parent = this.closest("bds-grid");
+    if (parent?.autoSpanMedia) return "auto";
+    return "full";
+  }
+  _teardownMedia() {
+    this._mediaCleanup?.();
+    this._mediaCleanup = void 0;
+  }
+  _resolveAutoSpan() {
+    this._teardownMedia();
+    if (this._effectiveColumnSpan() !== "auto") return;
+    const media = findMediaChild(this);
+    if (!media) {
+      this._setAutoSpan("one-quarter");
+      return;
+    }
+    const aspect = readMediaAspect(media);
+    if (aspect !== null) {
+      this._setAutoSpan(aspectToColumnSpan(aspect));
+      return;
+    }
+    const event = mediaReadyEvent(media);
+    if (!event) {
+      this._setAutoSpan("one-quarter");
+      return;
+    }
+    const handler = () => {
+      const a = readMediaAspect(media);
+      if (a !== null) this._setAutoSpan(aspectToColumnSpan(a));
+    };
+    media.addEventListener(event, handler, { once: true });
+    this._mediaCleanup = () => media.removeEventListener(event, handler);
+  }
+  _setAutoSpan(next) {
+    if (this._autoSpan === next) return;
+    this._autoSpan = next;
+    this.requestUpdate();
+  }
+  updated() {
+    const effective = this._effectiveColumnSpan();
+    if (effective === "auto") this._resolveAutoSpan();
+    const hasExplicitRange = this.startColumn !== void 0 || this.endColumn !== void 0;
+    const resolved = effective === "auto" ? this._autoSpan : effective;
+    const gridColumn = hasExplicitRange ? `${this.startColumn ?? "auto"} / ${this.endColumn ?? "auto"}` : resolveSpan(resolved);
+    this.style.gridColumn = gridColumn;
+    this.style.gridRow = this.rowSpan !== void 0 ? `span ${this.rowSpan}` : "";
+  }
+  render() {
+    return T`<slot></slot>`;
+  }
+};
+customElements.define("bds-grid-item", BdsGridItem);
+
 // src/web-components/ui/bds-button-group.ts
 var BdsButtonGroup = class extends i2 {
   static styles = i`
@@ -1631,6 +1940,8 @@ export {
   BdsDropdownMenuItem,
   BdsFileInput,
   BdsFormInput,
+  BdsGrid,
+  BdsGridItem,
   BdsIconWrapper,
   BdsLink,
   BdsLoading,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boostdev/design-system-components",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "BoostDev React component library: accessible, token-driven components built on @boostdev/design-system-foundation",
   "keywords": [
     "React",