@waggylabs/yumekit 0.4.2-beta.30 → 0.4.2-beta.32

package/CHANGELOG.md

@@ -31,6 +31,12 @@ Delete any empty sections before publishing.
 <!-- ### Security -->
 <!-- Vulnerability patches or hardening changes -->
 
+## [Unreleased]
+
+### Added
+
+- New `y-stack` component — a layout container for arranging child elements in rows, columns, grids, or masonry patterns. Supports `mode` (`"flex"` | `"grid"` | `"masonry"`), `direction`, `columns`, `gap` (maps to `--spacing-*` tokens), `wrap`, `align`, `justify`, and `responsive` attributes. Masonry mode uses JS absolute positioning with `ResizeObserver`. Responsive mode auto-collapses columns at configurable breakpoints. CSS custom properties: `--component-stack-gap`, `--component-stack-columns`, `--component-stack-mobile-breakpoint`, `--component-stack-tablet-breakpoint`.
+
 ## [0.4.2] - 2026-04-07
 
 ### Added

package/README.md

@@ -17,7 +17,7 @@
 
 ## Overview
 
-YumeKit is a collection of 27 production-ready custom elements built with native Web Components. It works with any framework — or none at all — and ships with a comprehensive design token system, built-in theming, an icon registry, and full TypeScript support.
+YumeKit is a collection of 30 production-ready custom elements built with native Web Components. It works with any framework — or none at all — and ships with a comprehensive design token system, built-in theming, an icon registry, and full TypeScript support.
 
 - **Zero dependencies** — built entirely on web standards
 - **Framework-agnostic** — works with React, Vue, Svelte, or plain HTML
@@ -96,6 +96,7 @@ Then use the `<y-theme>` component to apply a theme:
 | Rating       | `<y-rating>`       | Star / icon rating input                            |
 | Select       | `<y-select>`       | Select / dropdown input                             |
 | Slider       | `<y-slider>`       | Range slider input                                  |
+| Stack        | `<y-stack>`        | Layout container (row, column, grid, masonry)       |
 | Switch       | `<y-switch>`       | Toggle switch                                       |
 | Table        | `<y-table>`        | Sortable data table                                 |
 | Textarea     | `<y-textarea>`     | Multi-line text input                               |

package/dist/components/y-stack/y-stack.d.ts

@@ -0,0 +1,52 @@
+export class YumeStack extends HTMLElement {
+    static get observedAttributes(): string[];
+    _resizeObserver: ResizeObserver;
+    _masonryRAF: number;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(name: any, oldValue: any, newValue: any): void;
+    set direction(val: string);
+    /** Main axis direction (flex mode only). */
+    get direction(): string;
+    set mode(val: string);
+    /** Layout algorithm: "flex" | "grid" | "masonry". */
+    get mode(): string;
+    set columns(val: number);
+    /** Number of columns (grid/masonry modes). */
+    get columns(): number;
+    set gap(val: string);
+    /** Gap between items, maps to --spacing-* tokens. */
+    get gap(): string;
+    set wrap(val: boolean);
+    /** Allow items to wrap (flex mode only). */
+    get wrap(): boolean;
+    set align(val: string);
+    /** Cross-axis alignment. */
+    get align(): string;
+    set justify(val: string);
+    /** Main-axis distribution (flex mode only). */
+    get justify(): string;
+    set responsive(val: boolean);
+    /** Auto-reduce columns at narrow viewports. */
+    get responsive(): boolean;
+    render(): void;
+    _container: Element;
+    _slot: HTMLSlotElement;
+    _applyLayout(): void;
+    _buildStyleSheet(): CSSStyleSheet;
+    _buildResponsiveFlexCSS(): string;
+    _buildResponsiveGridCSS(cols: any): string;
+    _clearMasonryPositions(): void;
+    _getBreakpointValue(prop: any, fallback: any): any;
+    _getResolvedColumns(): any;
+    _getResponsiveColumns(): any;
+    _getSlottedElements(): Element[];
+    _initMasonry(): void;
+    _observedItems: Set<any>;
+    _initResponsive(): void;
+    _layoutMasonry(): void;
+    _resolveGap(): string;
+    _resolveGapPx(): number;
+    _syncMasonryObserver(): void;
+    _teardownMasonry(): void;
+}

package/dist/components/y-stack/y-stack.stories.d.ts

@@ -0,0 +1,195 @@
+declare namespace _default {
+    let title: string;
+    let tags: string[];
+    namespace argTypes {
+        namespace mode {
+            let control: string;
+            let options: string[];
+            let description: string;
+            namespace table {
+                namespace defaultValue {
+                    let summary: string;
+                }
+            }
+        }
+        namespace direction {
+            let control_1: string;
+            export { control_1 as control };
+            let options_1: string[];
+            export { options_1 as options };
+            let description_1: string;
+            export { description_1 as description };
+            export namespace table_1 {
+                export namespace defaultValue_1 {
+                    let summary_1: string;
+                    export { summary_1 as summary };
+                }
+                export { defaultValue_1 as defaultValue };
+            }
+            export { table_1 as table };
+        }
+        namespace gap {
+            let control_2: string;
+            export { control_2 as control };
+            let options_2: string[];
+            export { options_2 as options };
+            let description_2: string;
+            export { description_2 as description };
+            export namespace table_2 {
+                export namespace defaultValue_2 {
+                    let summary_2: string;
+                    export { summary_2 as summary };
+                }
+                export { defaultValue_2 as defaultValue };
+            }
+            export { table_2 as table };
+        }
+        namespace columns {
+            export namespace control_3 {
+                let type: string;
+                let min: number;
+                let max: number;
+            }
+            export { control_3 as control };
+            let description_3: string;
+            export { description_3 as description };
+            export namespace table_3 {
+                export namespace defaultValue_3 {
+                    let summary_3: number;
+                    export { summary_3 as summary };
+                }
+                export { defaultValue_3 as defaultValue };
+            }
+            export { table_3 as table };
+        }
+        namespace wrap {
+            let control_4: string;
+            export { control_4 as control };
+            let description_4: string;
+            export { description_4 as description };
+            export namespace table_4 {
+                export namespace defaultValue_4 {
+                    let summary_4: boolean;
+                    export { summary_4 as summary };
+                }
+                export { defaultValue_4 as defaultValue };
+            }
+            export { table_4 as table };
+        }
+        namespace align {
+            let control_5: string;
+            export { control_5 as control };
+            let options_3: string[];
+            export { options_3 as options };
+            let description_5: string;
+            export { description_5 as description };
+            export namespace table_5 {
+                export namespace defaultValue_5 {
+                    let summary_5: string;
+                    export { summary_5 as summary };
+                }
+                export { defaultValue_5 as defaultValue };
+            }
+            export { table_5 as table };
+        }
+        namespace justify {
+            let control_6: string;
+            export { control_6 as control };
+            let options_4: string[];
+            export { options_4 as options };
+            let description_6: string;
+            export { description_6 as description };
+            export namespace table_6 {
+                export namespace defaultValue_6 {
+                    let summary_6: string;
+                    export { summary_6 as summary };
+                }
+                export { defaultValue_6 as defaultValue };
+            }
+            export { table_6 as table };
+        }
+        namespace responsive {
+            let control_7: string;
+            export { control_7 as control };
+            let description_7: string;
+            export { description_7 as description };
+            export namespace table_7 {
+                export namespace defaultValue_7 {
+                    let summary_7: boolean;
+                    export { summary_7 as summary };
+                }
+                export { defaultValue_7 as defaultValue };
+            }
+            export { table_7 as table };
+        }
+    }
+    namespace args {
+        let mode_1: string;
+        export { mode_1 as mode };
+        let direction_1: string;
+        export { direction_1 as direction };
+        let gap_1: string;
+        export { gap_1 as gap };
+        let columns_1: number;
+        export { columns_1 as columns };
+        let wrap_1: boolean;
+        export { wrap_1 as wrap };
+        let align_1: string;
+        export { align_1 as align };
+        let justify_1: string;
+        export { justify_1 as justify };
+        let responsive_1: boolean;
+        export { responsive_1 as responsive };
+    }
+    function render({ mode, direction, gap, columns, wrap, align, justify, responsive }: {
+        mode: any;
+        direction: any;
+        gap: any;
+        columns: any;
+        wrap: any;
+        align: any;
+        justify: any;
+        responsive: any;
+    }): string;
+}
+export default _default;
+export const Default: {};
+export namespace Row {
+    export function render_1(): string;
+    export { render_1 as render };
+}
+export namespace Column {
+    export function render_2(): string;
+    export { render_2 as render };
+}
+export namespace RowWithJustify {
+    export function render_3(): string;
+    export { render_3 as render };
+}
+export namespace GapSizes {
+    export function render_4(): string;
+    export { render_4 as render };
+}
+export namespace Grid {
+    export function render_5(): string;
+    export { render_5 as render };
+}
+export namespace GridResponsive {
+    export let name: string;
+    export function render_6(): string;
+    export { render_6 as render };
+}
+export namespace Masonry {
+    export function render_7(): string;
+    export { render_7 as render };
+}
+export namespace WrapMode {
+    let name_1: string;
+    export { name_1 as name };
+    export function render_8(): string;
+    export { render_8 as render };
+}
+export namespace AlignCenter {
+    export function render_9(): string;
+    export { render_9 as render };
+}

package/dist/components/y-stack/y-stack.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/components/y-stack.js

@@ -0,0 +1,411 @@
+class YumeStack extends HTMLElement {
+    static get observedAttributes() {
+        return [
+            "direction",
+            "mode",
+            "columns",
+            "gap",
+            "wrap",
+            "align",
+            "justify",
+            "responsive",
+        ];
+    }
+
+    // -------------------------------------------------------------------------
+    // Lifecycle
+    // -------------------------------------------------------------------------
+
+    constructor() {
+        super();
+        this.attachShadow({ mode: "open" });
+        this._resizeObserver = null;
+        this._masonryRAF = null;
+        this.render();
+    }
+
+    connectedCallback() {
+        this._applyLayout();
+        if (this.mode === "masonry") this._initMasonry();
+        if (this.responsive) this._initResponsive();
+    }
+
+    disconnectedCallback() {
+        this._teardownMasonry();
+    }
+
+    attributeChangedCallback(name, oldValue, newValue) {
+        if (oldValue === newValue) return;
+
+        const wasMasonry = name === "mode" && oldValue === "masonry";
+        const isMasonry = this.mode === "masonry";
+
+        if (wasMasonry) this._teardownMasonry();
+
+        this._applyLayout();
+
+        if (isMasonry && this.isConnected) this._initMasonry();
+        if (name === "responsive" && this.responsive && this.isConnected)
+            this._initResponsive();
+    }
+
+    // -------------------------------------------------------------------------
+    // Getters / Setters
+    // -------------------------------------------------------------------------
+
+    /** Main axis direction (flex mode only). */
+    get direction() {
+        return this.getAttribute("direction") || "row";
+    }
+    set direction(val) {
+        this.setAttribute("direction", val);
+    }
+
+    /** Layout algorithm: "flex" | "grid" | "masonry". */
+    get mode() {
+        return this.getAttribute("mode") || "flex";
+    }
+    set mode(val) {
+        this.setAttribute("mode", val);
+    }
+
+    /** Number of columns (grid/masonry modes). */
+    get columns() {
+        return parseInt(this.getAttribute("columns"), 10) || 3;
+    }
+    set columns(val) {
+        this.setAttribute("columns", String(val));
+    }
+
+    /** Gap between items, maps to --spacing-* tokens. */
+    get gap() {
+        return this.getAttribute("gap") || "medium";
+    }
+    set gap(val) {
+        this.setAttribute("gap", val);
+    }
+
+    /** Allow items to wrap (flex mode only). */
+    get wrap() {
+        return this.hasAttribute("wrap");
+    }
+    set wrap(val) {
+        if (val) this.setAttribute("wrap", "");
+        else this.removeAttribute("wrap");
+    }
+
+    /** Cross-axis alignment. */
+    get align() {
+        return this.getAttribute("align") || "stretch";
+    }
+    set align(val) {
+        this.setAttribute("align", val);
+    }
+
+    /** Main-axis distribution (flex mode only). */
+    get justify() {
+        return this.getAttribute("justify") || "start";
+    }
+    set justify(val) {
+        this.setAttribute("justify", val);
+    }
+
+    /** Auto-reduce columns at narrow viewports. */
+    get responsive() {
+        return this.hasAttribute("responsive");
+    }
+    set responsive(val) {
+        if (val) this.setAttribute("responsive", "");
+        else this.removeAttribute("responsive");
+    }
+
+    // -------------------------------------------------------------------------
+    // Public
+    // -------------------------------------------------------------------------
+
+    render() {
+        this.shadowRoot.innerHTML = `<div class="container" part="container"><slot></slot></div>`;
+        this._container = this.shadowRoot.querySelector(".container");
+        this._slot = this.shadowRoot.querySelector("slot");
+        this._slot.addEventListener("slotchange", () => {
+            if (this.mode === "masonry") this._syncMasonryObserver();
+        });
+    }
+
+    // -------------------------------------------------------------------------
+    // Private
+    // -------------------------------------------------------------------------
+
+    _applyLayout() {
+        if (!this._container) return;
+        const sheet = this._buildStyleSheet();
+        this.shadowRoot.adoptedStyleSheets = [sheet];
+
+        if (this.mode === "masonry") {
+            this._layoutMasonry();
+        } else {
+            this._clearMasonryPositions();
+        }
+    }
+
+    _buildStyleSheet() {
+        const sheet = new CSSStyleSheet();
+        const gapValue = this._resolveGap();
+        const mode = this.mode;
+        const cols = this.columns;
+        const responsive = this.responsive;
+
+        let containerCSS;
+        let responsiveCSS = "";
+
+        if (mode === "grid") {
+            containerCSS = `
+                .container {
+                    display: grid;
+                    grid-template-columns: repeat(var(--component-stack-columns, ${cols}), 1fr);
+                    gap: ${gapValue};
+                }
+            `;
+            if (responsive) {
+                responsiveCSS = this._buildResponsiveGridCSS(cols);
+            }
+        } else if (mode === "masonry") {
+            containerCSS = `
+                .container {
+                    position: relative;
+                }
+            `;
+        } else {
+            const dir = this.direction;
+            const alignMap = {
+                start: "flex-start",
+                end: "flex-end",
+                center: "center",
+                stretch: "stretch",
+                baseline: "baseline",
+            };
+            const justifyMap = {
+                start: "flex-start",
+                end: "flex-end",
+                center: "center",
+                between: "space-between",
+                around: "space-around",
+                evenly: "space-evenly",
+            };
+
+            containerCSS = `
+                .container {
+                    display: flex;
+                    flex-direction: ${dir};
+                    flex-wrap: ${this.wrap ? "wrap" : "nowrap"};
+                    align-items: ${alignMap[this.align] || "stretch"};
+                    justify-content: ${justifyMap[this.justify] || "flex-start"};
+                    gap: ${gapValue};
+                }
+            `;
+            if (responsive && dir === "row") {
+                responsiveCSS = this._buildResponsiveFlexCSS();
+            }
+        }
+
+        sheet.replaceSync(`
+            :host {
+                display: block;
+                box-sizing: border-box;
+            }
+            ${containerCSS}
+            ${responsiveCSS}
+        `);
+        return sheet;
+    }
+
+    _buildResponsiveFlexCSS() {
+        return `
+            @media (max-width: var(--component-stack-mobile-breakpoint, 576px)) {
+                .container {
+                    flex-direction: column;
+                }
+            }
+        `;
+    }
+
+    _buildResponsiveGridCSS(cols) {
+        const tabletCols = Math.min(2, cols);
+        return `
+            @media (max-width: var(--component-stack-tablet-breakpoint, 768px)) {
+                .container {
+                    grid-template-columns: repeat(${tabletCols}, 1fr);
+                }
+            }
+            @media (max-width: var(--component-stack-mobile-breakpoint, 576px)) {
+                .container {
+                    grid-template-columns: 1fr;
+                }
+            }
+        `;
+    }
+
+    _clearMasonryPositions() {
+        const items = this._getSlottedElements();
+        items.forEach((item) => {
+            item.style.position = "";
+            item.style.top = "";
+            item.style.left = "";
+            item.style.width = "";
+        });
+        if (this._container) {
+            this._container.style.height = "";
+        }
+    }
+
+    _getBreakpointValue(prop, fallback) {
+        const val = getComputedStyle(this).getPropertyValue(prop).trim();
+        return val ? parseInt(val, 10) : fallback;
+    }
+
+    _getResolvedColumns() {
+        return this._getBreakpointValue(
+            "--component-stack-columns",
+            this.columns,
+        );
+    }
+
+    _getResponsiveColumns() {
+        const cols = this._getResolvedColumns();
+        const mobileBreakpoint = this._getBreakpointValue(
+            "--component-stack-mobile-breakpoint",
+            576,
+        );
+        const tabletBreakpoint = this._getBreakpointValue(
+            "--component-stack-tablet-breakpoint",
+            768,
+        );
+        const width = this._container
+            ? this._container.offsetWidth
+            : window.innerWidth;
+
+        if (width <= mobileBreakpoint) return 1;
+        if (width <= tabletBreakpoint) return Math.min(2, cols);
+        return cols;
+    }
+
+    _getSlottedElements() {
+        if (!this._slot) return [];
+        return this._slot.assignedElements({ flatten: true });
+    }
+
+    _initMasonry() {
+        this._teardownMasonry();
+        this._observedItems = new Set();
+        this._resizeObserver = new ResizeObserver(() => {
+            if (this._masonryRAF) cancelAnimationFrame(this._masonryRAF);
+            this._masonryRAF = requestAnimationFrame(() =>
+                this._layoutMasonry(),
+            );
+        });
+        this._resizeObserver.observe(this._container);
+        this._syncMasonryObserver();
+    }
+
+    _initResponsive() {
+        if (this.mode !== "masonry") return;
+        if (!this._resizeObserver) this._initMasonry();
+    }
+
+    _layoutMasonry() {
+        const items = this._getSlottedElements();
+        if (!items.length || !this._container) return;
+
+        const cols = this.responsive
+            ? this._getResponsiveColumns()
+            : this._getResolvedColumns();
+        const gapPx = this._resolveGapPx();
+        const containerWidth = this._container.offsetWidth;
+        const colWidth = (containerWidth - gapPx * (cols - 1)) / cols;
+
+        const colHeights = new Array(cols).fill(0);
+
+        items.forEach((item) => {
+            const shortest = colHeights.indexOf(Math.min(...colHeights));
+            const x = shortest * (colWidth + gapPx);
+            const y = colHeights[shortest];
+
+            item.style.position = "absolute";
+            item.style.top = `${y}px`;
+            item.style.left = `${x}px`;
+            item.style.width = `${colWidth}px`;
+
+            colHeights[shortest] += item.offsetHeight + gapPx;
+        });
+
+        this._container.style.height = `${Math.max(...colHeights) - gapPx}px`;
+    }
+
+    _resolveGap() {
+        const gapMap = {
+            none: "var(--spacing-none)",
+            "x-small": "var(--spacing-x-small)",
+            small: "var(--spacing-small)",
+            medium: "var(--spacing-medium)",
+            large: "var(--spacing-large)",
+            "x-large": "var(--spacing-x-large)",
+            "2x-large": "var(--spacing-2x-large)",
+            "4x-large": "var(--spacing-4x-large)",
+        };
+        return `var(--component-stack-gap, ${gapMap[this.gap] || gapMap.medium})`;
+    }
+
+    _resolveGapPx() {
+        const temp = document.createElement("div");
+        temp.style.position = "absolute";
+        temp.style.visibility = "hidden";
+        temp.style.width = this._resolveGap();
+        this._container.appendChild(temp);
+        const px = temp.offsetWidth;
+        temp.remove();
+        return px;
+    }
+
+    _syncMasonryObserver() {
+        if (!this._resizeObserver) {
+            this._initMasonry();
+            return;
+        }
+
+        const current = new Set(this._getSlottedElements());
+
+        for (const item of this._observedItems) {
+            if (!current.has(item)) {
+                this._resizeObserver.unobserve(item);
+                this._observedItems.delete(item);
+            }
+        }
+
+        for (const item of current) {
+            if (!this._observedItems.has(item)) {
+                this._resizeObserver.observe(item);
+                this._observedItems.add(item);
+            }
+        }
+
+        this._layoutMasonry();
+    }
+
+    _teardownMasonry() {
+        if (this._resizeObserver) {
+            this._resizeObserver.disconnect();
+            this._resizeObserver = null;
+            this._observedItems = null;
+        }
+        if (this._masonryRAF) {
+            cancelAnimationFrame(this._masonryRAF);
+            this._masonryRAF = null;
+        }
+    }
+}
+
+if (!customElements.get("y-stack")) {
+    customElements.define("y-stack", YumeStack);
+}
+
+export { YumeStack };