@waggylabs/yumekit 0.4.3-beta.40 → 0.4.3-beta.41

package/CHANGELOG.md

@@ -42,6 +42,12 @@ Delete any empty sections before publishing.
 - New `y-color` component — a form-associated color input with a trigger/popup pattern (like `<y-date>`). Renders a color swatch preview and value string in the trigger; opens a `<y-colorpicker>` popup on click. Supports `value`, `format`, `formats`, `show-alpha`, `placeholder`, `name`, `disabled`, `invalid`, `clearable`, `size`, and `label-position` attributes. Uses `ElementInternals` for `FormData` participation.
 - New `y-banner` component — a full-width informational banner that renders in a semantic color with matching text. Supports `color` (`"base"` | `"primary"` | `"secondary"` | `"success"` | `"error"` | `"warning"` | `"help"`), `icon` attribute (or `icon` slot), `position` (`"push"` | `"overlap"`), `sticky` (fixed to viewport when overlapping), `dismissable` close button, `size` (`"small"` | `"medium"` | `"large"`), and an `action` slot for CTA elements.
 - 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.
+- `y-tabs`: `leftIcon` and `rightIcon` properties on option objects — set a `<y-icon>` name directly in the options JSON to render icons without requiring extra child elements or named slots.
+- `y-tabs`: `tab-content-{id}` slot — place any content (icons, badges, custom markup) inside the tab button itself by targeting this slot. Takes full precedence over `leftIcon`/`rightIcon` and the default label rendering.
+
+### Deprecated
+
+- `y-tabs`: `left-icon-{id}` and `right-icon-{id}` slots — these slots still function but emit a `console.warn` directing users to the `leftIcon`/`rightIcon` option properties or the `tab-content-{id}` slot. They will be removed before the release of version 1.0.
 
 ## [0.4.2] - 2026-04-07
 

package/CONTRIBUTING.md

@@ -36,6 +36,62 @@ Yumekit is authored in plain JavaScript. Please follow the conventions already p
 - Keep components self-contained: styles live in the Shadow DOM, logic in the class, no shared global state.
 - Run the linter before submitting: `npm run lint`.
 
+## Component Authoring Guidelines
+
+### Class structure
+
+Every component class must have exactly four comment-delimited sections in this order — no more, no subdivisions:
+
+```
+// Lifecycle
+// Getters / Setters
+// Public
+// Private
+```
+
+Methods within their subdivision must be listed alphabetically.
+
+### Method style
+
+Follow a **define → compute → return/apply** flow within each method where possible: gather inputs and state at the top, do the work in the middle, produce output at the end. Keep methods small and focused — if a method grows long or does multiple distinct things, extract a named helper. Minimize nesting by preferring early returns over deep `if/else` trees. Separate distinct logical units of work with blank lines. This ruleset allows humans and AI to have a predictable and human-readable code structure upon which to base future updates.
+
+### DOM element creation
+
+Use the `createElement` helper (imported as `_el`) from `src/modules/helpers.js` for all element creation inside components. Do not use manual `document.createElement` + `setAttribute` chains.
+
+```js
+import { createElement as _el } from "../../modules/helpers.js";
+
+const btn = _el("button", { role: "tab", "aria-label": label }, [labelText]);
+```
+
+### Icons
+
+Use `<y-icon name="...">` for all icons. Never inline SVG strings or constants. Import `y-icon.js` at the top of any component that renders icons.
+
+### Slot patterns
+
+Always render named slots unconditionally and place default/fallback content as **children of the slot element**. Never use `querySelector` to decide whether to create a slot. This breaks framework rendering (React, Vue, etc.) where children may arrive after the element upgrades.
+
+```js
+// Correct
+const slot = _el("slot", { name: "icon" });
+slot.appendChild(defaultIcon);
+parent.appendChild(slot);
+
+// Wrong — slot is conditional on a render-time DOM query
+if (this.querySelector('[slot="icon"]')) { ... }
+```
+
+### New component checklist
+
+Every new component requireschanges to the following: `README.md`, `CHANGELOG.md`, `reference.md`, `SKILL.md`, `react.d.ts`, `variables.css`, `.figma/variables.json`, entry in `llm.txt`, and a `y-*.stories.js` stories file.
+
+### Testing
+
+- Tests co-locate with the component source file.
+- Use `sinon.createSandbox()` at the `describe` level with `afterEach(() => sandbox.restore())`.
+
 ## AI Assistance
 
 AI tools can be helpful for brainstorming and prototyping, but they are not a substitute for human judgment and expertise.

package/dist/components/y-breadcrumbs.js

@@ -395,25 +395,9 @@ class YumeBreadcrumbs extends HTMLElement {
             part: parts.join(" "),
         });
 
-        const iconSlotName = `${index}-icon`;
-        const hasIconSlot = !!this.querySelector(`[slot="${iconSlotName}"]`);
-
-        if (hasIconSlot) {
-            li.appendChild(
-                createElement("slot", { name: iconSlotName, class: "item-icon" }),
-            );
-        } else if (item.icon) {
-            li.appendChild(
-                createElement("y-icon", {
-                    name: item.icon,
-                    size: this._getIconSize(),
-                    class: "item-icon",
-                }),
-            );
-        }
-
+        let linkEl;
         if (isCurrent || !item.href) {
-            const span = createElement(
+            linkEl = createElement(
                 "span",
                 {
                     class: "link current-text",
@@ -422,9 +406,8 @@ class YumeBreadcrumbs extends HTMLElement {
                 },
                 [item.text],
             );
-            li.appendChild(span);
         } else {
-            const anchor = createElement(
+            linkEl = createElement(
                 "a",
                 {
                     class: "link",
@@ -433,14 +416,20 @@ class YumeBreadcrumbs extends HTMLElement {
                 },
                 [item.text],
             );
-
-            anchor.addEventListener("click", (e) => {
+            linkEl.addEventListener("click", (e) => {
                 if (e.button !== 0 || e.metaKey || e.ctrlKey || e.shiftKey || e.altKey) return;
                 this._onNavigate(e, item.href);
             });
+        }
 
-            li.appendChild(anchor);
+        const itemSlot = createElement("slot", { name: `${index}-item` });
+        if (item.icon) {
+            itemSlot.appendChild(
+                createElement("y-icon", { name: item.icon, size: this._getIconSize(), class: "item-icon" }),
+            );
         }
+        itemSlot.appendChild(linkEl);
+        li.appendChild(itemSlot);
 
         return li;
     }

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

@@ -1,10 +1,11 @@
 export class YumeTabs extends HTMLElement {
     static get observedAttributes(): string[];
     _activeTab: string;
+    _warnedSlots: Set<any>;
     connectedCallback(): void;
     attributeChangedCallback(name: any, oldVal: any, newVal: any): void;
     set options(val: Array<any>);
-    /** @type {Array<Object>} Tab definitions with id, label, slot, and optional disabled flag. */
+    /** @type {Array<Object>} Tab definitions. Each object: `{ id, label, slot, disabled?, leftIcon?, rightIcon? }`. `leftIcon`/`rightIcon` are `y-icon` names rendered inside the tab button. Use the `tab-content-{id}` slot to supply fully custom tab button content instead. */
     get options(): Array<any>;
     set position(val: "top" | "bottom" | "left" | "right");
     /** @type {"top"|"bottom"|"left"|"right"} Which edge the tab strip is placed on. */
@@ -18,8 +19,10 @@ export class YumeTabs extends HTMLElement {
      */
     activateTab(id: string): void;
     render(): void;
-    _createPanel(slotName: any): HTMLDivElement;
-    _createTabButton(tab: any): HTMLButtonElement;
+    _appendDeprecatedIconSlot(parent: any, side: any, tabId: any): void;
+    _createIcon(name: any): HTMLElement;
+    _createPanel(slotName: any): HTMLElement;
+    _createTabButton(tab: any): HTMLElement;
     _findSiblingButton(buttons: any, fromIndex: any, direction: any): any;
     _getStyles(): string;
     _handleTabKeydown(e: any, buttons: any): void;

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

@@ -1,10 +1,11 @@
 export class YumeTabs extends HTMLElement {
     static get observedAttributes(): string[];
     _activeTab: string;
+    _warnedSlots: Set<any>;
     connectedCallback(): void;
     attributeChangedCallback(name: any, oldVal: any, newVal: any): void;
     set options(val: Array<any>);
-    /** @type {Array<Object>} Tab definitions with id, label, slot, and optional disabled flag. */
+    /** @type {Array<Object>} Tab definitions. Each object: `{ id, label, slot, disabled?, leftIcon?, rightIcon? }`. `leftIcon`/`rightIcon` are `y-icon` names rendered inside the tab button. Use the `tab-content-{id}` slot to supply fully custom tab button content instead. */
     get options(): Array<any>;
     set position(val: "top" | "bottom" | "left" | "right");
     /** @type {"top"|"bottom"|"left"|"right"} Which edge the tab strip is placed on. */
@@ -18,8 +19,10 @@ export class YumeTabs extends HTMLElement {
      */
     activateTab(id: string): void;
     render(): void;
-    _createPanel(slotName: any): HTMLDivElement;
-    _createTabButton(tab: any): HTMLButtonElement;
+    _appendDeprecatedIconSlot(parent: any, side: any, tabId: any): void;
+    _createIcon(name: any): HTMLElement;
+    _createPanel(slotName: any): HTMLElement;
+    _createTabButton(tab: any): HTMLElement;
     _findSiblingButton(buttons: any, fromIndex: any, direction: any): any;
     _getStyles(): string;
     _handleTabKeydown(e: any, buttons: any): void;

package/dist/components/y-tabs.js

@@ -1,3 +1,222 @@
+import { getIcon } from '../../icons/registry.js';
+import { createElement } from '../../modules/helpers.js';
+
+// Allowlist-based SVG sanitizer — only known-safe elements and attributes are kept.
+const ALLOWED_ELEMENTS = new Set([
+    "svg", "g", "path", "circle", "ellipse", "rect", "line", "polyline",
+    "polygon", "text", "tspan", "defs", "clippath", "mask", "lineargradient",
+    "radialgradient", "stop", "symbol", "title", "desc", "metadata",
+]);
+
+const ALLOWED_ATTRS = new Set([
+    "viewbox", "xmlns", "fill", "stroke", "stroke-width", "stroke-linecap",
+    "stroke-linejoin", "stroke-dasharray", "stroke-dashoffset", "stroke-miterlimit",
+    "stroke-opacity", "fill-opacity", "fill-rule", "clip-rule", "opacity",
+    "d", "cx", "cy", "r", "rx", "ry", "x", "x1", "x2", "y", "y1", "y2",
+    "width", "height", "points", "transform", "id", "class", "clip-path", "mask",
+    "offset", "stop-color", "stop-opacity", "gradient-units", "gradienttransform",
+    "gradientunits", "spreadmethod", "patternunits", "patterntransform",
+    "font-size", "font-family", "font-weight", "text-anchor", "dominant-baseline",
+    "alignment-baseline", "dx", "dy", "rotate", "textlength", "lengthadjust",
+    "display", "visibility", "color", "vector-effect",
+]);
+
+function sanitizeSvg(raw) {
+    if (!raw) return "";
+    const doc = new DOMParser().parseFromString(raw, "image/svg+xml");
+    const svg = doc.querySelector("svg");
+    if (!svg) return "";
+
+    const walk = (el) => {
+        for (const child of [...el.children]) {
+            if (!ALLOWED_ELEMENTS.has(child.tagName.toLowerCase())) {
+                child.remove();
+                continue;
+            }
+            for (const attr of [...child.attributes]) {
+                if (!ALLOWED_ATTRS.has(attr.name.toLowerCase())) {
+                    child.removeAttribute(attr.name);
+                }
+            }
+            walk(child);
+        }
+    };
+
+    for (const attr of [...svg.attributes]) {
+        if (!ALLOWED_ATTRS.has(attr.name.toLowerCase())) {
+            svg.removeAttribute(attr.name);
+        }
+    }
+    walk(svg);
+    return svg.outerHTML;
+}
+
+// Cache sanitized SVG markup per icon name to avoid repeated DOMParser + DOM-walk
+// on every render. The cache is naturally bounded by the number of registered icons.
+const sanitizedSvgCache = new Map();
+
+function getCachedSvg(name) {
+    if (sanitizedSvgCache.has(name)) return sanitizedSvgCache.get(name);
+    const result = sanitizeSvg(getIcon(name));
+    sanitizedSvgCache.set(name, result);
+    return result;
+}
+
+class YumeIcon extends HTMLElement {
+    static get observedAttributes() {
+        return ["name", "size", "color", "label", "weight"];
+    }
+
+    // -------------------------------------------------------------------------
+    // Lifecycle
+    // -------------------------------------------------------------------------
+
+    constructor() {
+        super();
+        this.attachShadow({ mode: "open" });
+    }
+
+    connectedCallback() {
+        this.render();
+    }
+
+    attributeChangedCallback(name, oldVal, newVal) {
+        if (oldVal === newVal) return;
+        this.render();
+    }
+
+    // -------------------------------------------------------------------------
+    // Getters / Setters
+    // -------------------------------------------------------------------------
+
+    /** Color theme: "base" | "primary" | "secondary" | "success" | "warning" | "error" | "help". */
+    get color() { return this.getAttribute("color") || ""; }
+    set color(val) {
+        if (val) this.setAttribute("color", val);
+        else this.removeAttribute("color");
+    }
+
+    /** Accessible label for the icon. When set, the icon gets role="img". */
+    get label() { return this.getAttribute("label") || ""; }
+    set label(val) {
+        if (val) this.setAttribute("label", val);
+        else this.removeAttribute("label");
+    }
+
+    /** The registered icon name to display. */
+    get name() { return this.getAttribute("name") || ""; }
+    set name(val) { this.setAttribute("name", val); }
+
+    /** Icon size: "x-small" | "small" | "medium" | "large" | "x-large" (default "medium"). */
+    get size() { return this.getAttribute("size") || "medium"; }
+    set size(val) { this.setAttribute("size", val); }
+
+    /** Stroke weight: "thin" | "regular" | "thick". */
+    get weight() { return this.getAttribute("weight") || "regular"; }
+    set weight(val) {
+        if (val) this.setAttribute("weight", val);
+        else this.removeAttribute("weight");
+    }
+
+    // -------------------------------------------------------------------------
+    // Public
+    // -------------------------------------------------------------------------
+
+    render() {
+        const svg = getCachedSvg(this.name);
+        const sizeVal = this._getSize(this.size);
+        const colorVal = this.color ? this._getColor(this.color) : "inherit";
+        const weightVal = this._getWeight(this.weight);
+
+        this._updateAria();
+
+        this.shadowRoot.innerHTML = `
+            <style>
+                :host {
+                    display: inline-flex;
+                    align-items: center;
+                    justify-content: center;
+                    width: ${sizeVal};
+                    height: ${sizeVal};
+                    color: ${colorVal};
+                    line-height: 0;
+                }
+                .icon-wrapper svg {
+                    width: 100%;
+                    height: 100%;
+                }
+                ${this._getWeightCSS(weightVal)}
+            </style>
+            <span class="icon-wrapper" part="icon">${svg}</span>
+        `;
+    }
+
+    // -------------------------------------------------------------------------
+    // Private
+    // -------------------------------------------------------------------------
+
+    _getColor(color) {
+        const map = {
+            base: "var(--base-content--, #f7f7fa)",
+            primary: "var(--primary-content--, #0576ff)",
+            secondary: "var(--secondary-content--, #04b8b8)",
+            success: "var(--success-content--, #2dba73)",
+            warning: "var(--warning-content--, #d17f04)",
+            error: "var(--error-content--, #b80421)",
+            help: "var(--help-content--, #5405ff)",
+        };
+        if (map[color]) return map[color];
+        if (color && (color.startsWith("#") || color.startsWith("rgb") || color.startsWith("hsl"))) {
+            return color;
+        }
+        return map.base;
+    }
+
+    _getSize(size) {
+        const map = {
+            "x-small": "var(--component-icon-size-x-small, 10px)",
+            small: "var(--component-icon-size-small, 14px)",
+            medium: "var(--component-icon-size-medium, 18px)",
+            large: "var(--component-icon-size-large, 22px)",
+            "x-large": "var(--component-icon-size-x-large, 28px)",
+        };
+        return map[size] || map.medium;
+    }
+
+    _getWeight(weight) {
+        const map = {
+            "x-thin":  "1",
+            thin:      "1.5",
+            regular:   "2",
+            thick:     "2.5",
+            "x-thick": "3",
+        };
+        return map[weight] || "";
+    }
+
+    _getWeightCSS(weightVal) {
+        if (!weightVal) return "";
+        return `.icon-wrapper svg,
+                .icon-wrapper svg * { stroke-width: ${weightVal} !important; }`;
+    }
+
+    _updateAria() {
+        if (this.label) {
+            this.setAttribute("role", "img");
+            this.setAttribute("aria-label", this.label);
+            this.removeAttribute("aria-hidden");
+        } else {
+            this.setAttribute("aria-hidden", "true");
+            this.removeAttribute("role");
+            this.removeAttribute("aria-label");
+        }
+    }
+}
+
+if (!customElements.get("y-icon")) {
+    customElements.define("y-icon", YumeIcon);
+}
+
 class YumeTabs extends HTMLElement {
     static get observedAttributes() {
         return ["options", "size", "position"];
@@ -11,6 +230,7 @@ class YumeTabs extends HTMLElement {
         super();
         this.attachShadow({ mode: "open" });
         this._activeTab = "";
+        this._warnedSlots = new Set();
     }
 
     connectedCallback() {
@@ -20,16 +240,16 @@ class YumeTabs extends HTMLElement {
     }
 
     attributeChangedCallback(name, oldVal, newVal) {
-        if ((name === "options" || name === "size" || name === "position") && oldVal !== newVal) {
-            this.render();
-        }
+        if (oldVal === newVal) return;
+        if (name === "options") this._warnedSlots.clear();
+        this.render();
     }
 
     // -------------------------------------------------------------------------
     // Getters / Setters
     // -------------------------------------------------------------------------
 
-    /** @type {Array<Object>} Tab definitions with id, label, slot, and optional disabled flag. */
+    /** @type {Array<Object>} Tab definitions. Each object: `{ id, label, slot, disabled?, leftIcon?, rightIcon? }`. `leftIcon`/`rightIcon` are `y-icon` names rendered inside the tab button. Use the `tab-content-{id}` slot to supply fully custom tab button content instead. */
     get options() {
         try {
             return JSON.parse(this.getAttribute("options") || "[]");
@@ -88,10 +308,7 @@ class YumeTabs extends HTMLElement {
         style.textContent = this._getStyles();
         this.shadowRoot.appendChild(style);
 
-        const tablist = document.createElement("div");
-        tablist.className = "tablist";
-        tablist.setAttribute("role", "tablist");
-        tablist.setAttribute("part", "tablist");
+        const tablist = createElement("div", { class: "tablist", role: "tablist", part: "tablist" });
         tabs.forEach((tab) => tablist.appendChild(this._createTabButton(tab)));
         this.shadowRoot.appendChild(tablist);
 
@@ -104,17 +321,38 @@ class YumeTabs extends HTMLElement {
     // Private
     // -------------------------------------------------------------------------
 
+    _appendDeprecatedIconSlot(parent, side, tabId) {
+        const slotName = `${side}-icon-${tabId}`;
+
+        if (!this.querySelector(`[slot="${slotName}"]`)) return;
+
+        if (!this._warnedSlots.has(slotName)) {
+            this._warnedSlots.add(slotName);
+            // eslint-disable-next-line no-console
+            console.warn(
+                `[y-tabs] The "${slotName}" slot is deprecated. ` +
+                `Use the ${side}Icon property on the tab options object instead, ` +
+                `or use the "tab-content-${tabId}" slot for custom content.`
+            );
+        }
+
+        parent.appendChild(createElement("slot", { name: slotName, class: "icon-slot" }));
+    }
+
+    _createIcon(name) {
+        return createElement("y-icon", { name, size: this.size });
+    }
+
     _createPanel(slotName) {
-        const panel = document.createElement("div");
-        panel.className = "tabpanel";
-        panel.id = `panel-${this._activeTab}`;
-        panel.setAttribute("role", "tabpanel");
-        panel.setAttribute("part", "content");
-        panel.setAttribute("aria-labelledby", `tab-${this._activeTab}`);
+        const panel = createElement("div", {
+            class: "tabpanel",
+            id: `panel-${this._activeTab}`,
+            role: "tabpanel",
+            part: "content",
+            "aria-labelledby": `tab-${this._activeTab}`,
+        });
 
-        const contentSlot = document.createElement("slot");
-        contentSlot.name = slotName;
-        panel.appendChild(contentSlot);
+        panel.appendChild(createElement("slot", { name: slotName }));
 
         return panel;
     }
@@ -122,35 +360,36 @@ class YumeTabs extends HTMLElement {
     _createTabButton(tab) {
         const isActive = tab.id === this._activeTab;
         const isDisabled = !!tab.disabled;
-        const btn = document.createElement("button");
 
-        btn.id = `tab-${tab.id}`;
-        btn.setAttribute("role", "tab");
-        btn.setAttribute("part", "tab");
-        btn.setAttribute("aria-selected", isActive);
-        btn.setAttribute("aria-controls", `panel-${tab.id}`);
-        btn.setAttribute("aria-disabled", isDisabled);
+        const btn = createElement("button", {
+            id: `tab-${tab.id}`,
+            role: "tab",
+            part: "tab",
+            "aria-label": tab.label,
+            "aria-selected": String(isActive),
+            "aria-controls": `panel-${tab.id}`,
+            "aria-disabled": String(isDisabled),
+        });
 
         if (isDisabled) btn.disabled = true;
         btn.tabIndex = isActive && !isDisabled ? 0 : -1;
         btn.dataset.id = tab.id;
 
-        if (this.querySelector(`[slot="left-icon-${tab.id}"]`)) {
-            const leftSlot = document.createElement("slot");
-            leftSlot.name = `left-icon-${tab.id}`;
-            leftSlot.className = "icon-slot";
-            btn.appendChild(leftSlot);
+        const contentSlot = createElement("slot", { name: `tab-content-${tab.id}` });
+        btn.appendChild(contentSlot);
+
+        if (tab.leftIcon) {
+            contentSlot.appendChild(this._createIcon(tab.leftIcon));
+        } else {
+            this._appendDeprecatedIconSlot(contentSlot, "left", tab.id);
         }
 
-        const labelSpan = document.createElement("span");
-        labelSpan.textContent = tab.label;
-        btn.appendChild(labelSpan);
+        contentSlot.appendChild(createElement("span", {}, [tab.label]));
 
-        if (this.querySelector(`[slot="right-icon-${tab.id}"]`)) {
-            const rightSlot = document.createElement("slot");
-            rightSlot.name = `right-icon-${tab.id}`;
-            rightSlot.className = "icon-slot";
-            btn.appendChild(rightSlot);
+        if (tab.rightIcon) {
+            contentSlot.appendChild(this._createIcon(tab.rightIcon));
+        } else {
+            this._appendDeprecatedIconSlot(contentSlot, "right", tab.id);
         }
 
         return btn;
@@ -253,13 +492,20 @@ class YumeTabs extends HTMLElement {
 
     _handleTabKeydown(e, buttons) {
         const idx = buttons.indexOf(e.currentTarget);
+
         if (e.key === "ArrowRight") {
             e.preventDefault();
             this._findSiblingButton(buttons, idx, 1)?.focus();
-        } else if (e.key === "ArrowLeft") {
+            return;
+        }
+
+        if (e.key === "ArrowLeft") {
             e.preventDefault();
             this._findSiblingButton(buttons, idx, -1)?.focus();
-        } else if (e.key === "Enter" || e.key === " ") {
+            return;
+        }
+
+        if (e.key === "Enter" || e.key === " ") {
             e.preventDefault();
             this.activateTab(e.currentTarget.dataset.id);
         }
@@ -277,9 +523,7 @@ class YumeTabs extends HTMLElement {
         buttons.forEach((button) => {
             if (button.disabled) return;
             button.addEventListener("click", () => this.activateTab(button.dataset.id));
-            button.addEventListener("keydown", (e) => {
-                this._handleTabKeydown(e, buttons);
-            });
+            button.addEventListener("keydown", (e) => this._handleTabKeydown(e, buttons));
         });
     }
 }