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

package/CHANGELOG.md

@@ -35,6 +35,7 @@ Delete any empty sections before publishing.
 
 ### Added
 
+- New `y-dock` component — a fixed navigation bar (dock) that displays icon+label items for primary app navigation. Accepts items via a JSON `items` attribute, slotted templates, or direct child elements. Attributes: `items` (JSON array of `{ name, icon, href?, selected?, slot? }`), `position` (`"bottom"` | `"top"`), `breakpoint` (viewport width below which dock is visible — omit for always visible), `size` (`"small"` | `"medium"` | `"large"`), `history` (omit for `pushState` SPA navigation; set to `"false"` for full-page navigation). Events: cancelable `navigate` (`detail: { href }`). Full ARIA support with `role="navigation"`, `aria-current="page"`, and keyboard navigation (Arrow Left/Right, Enter/Space).
 - New `y-stepper` component — a multi-step wizard that guides users through a sequential flow. Step content is provided via named slots defined in the `items` JSON array (`{ label, slot, description?, icon?, status? }`). Supports `current` (zero-based active step index), `orientation` (`"horizontal"` | `"vertical"`), `position` (`"start"` | `"end"` — controls whether indicators appear before or after the content), `size` (`"small"` | `"medium"` | `"large"`), `linear` (restricts free navigation), and `editable` (allows returning to completed steps). Methods: `next()`, `previous()`, `goTo(index)`, `complete(index?)`, `reset()`. Events: cancelable `change`, `complete`, `finish`. Full ARIA support with `role="list"`, `aria-current="step"`, `aria-controls`/`aria-labelledby` linkage, and keyboard navigation.
 - New `y-breadcrumbs` component — a navigation breadcrumb trail. Accepts an `items` JSON array (`{ text, href?, icon? }`). Supports `separator` (custom separator character or slotted icon), `max-items` (collapses middle items with an expand button), `size` (`"small"` | `"medium"` | `"large"`), and `history` (set to `"false"` for full-page navigation instead of `pushState`). Fires cancelable `navigate` and `expand` events. Full ARIA with `<nav aria-label="Breadcrumb">`, `<ol>`, `aria-current="page"`, and `aria-hidden` separators.
 - New `y-gallery` component — a media gallery that accepts `<img>` or `<figure>` children and arranges them in `grid`, `row`, `column`, or `masonry` layouts. Supports `columns`, `gap` (`"small"` | `"medium"` | `"large"` or any CSS length), `aspect-ratio`, `expandable` (lightbox with prev/next navigation), `loop`, and `size` attributes. The expanded view uses `<y-icon>` for nav arrows and supports `data-src` for full-resolution images, `<figcaption>` captions, and image counter. Icon slots (`expand-prev-icon`, `expand-next-icon`, `expand-close-icon`) allow custom icons. Fires `expand`, `close`, and `navigate` events.

package/README.md

@@ -17,7 +17,7 @@
 
 ## Overview
 
-YumeKit is a collection of 34 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 35 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
@@ -86,6 +86,7 @@ Then use the `<y-theme>` component to apply a theme:
 | Date         | `<y-date>`         | Date input                                          |
 | DatePicker   | `<y-datepicker>`   | A date and time picker                              |
 | Dialog       | `<y-dialog>`       | Modal dialog                                        |
+| Dock         | `<y-dock>`         | Fixed navigation dock                               |
 | Drawer       | `<y-drawer>`       | Side drawer / sidebar                               |
 | Gallery      | `<y-gallery>`      | Media gallery with lightbox                         |
 | Icon         | `<y-icon>`         | SVG icon display                                    |

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

@@ -0,0 +1,32 @@
+export class YumeDock extends HTMLElement {
+    static get observedAttributes(): string[];
+    _mediaQuery: MediaQueryList;
+    _onMediaChange(e: any): void;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(name: any, oldValue: any, newValue: any): void;
+    set breakpoint(val: number);
+    /** Viewport width below which dock is visible (px). When omitted, always visible. */
+    get breakpoint(): number;
+    set history(val: string);
+    /** Navigation mode. Omit for pushState SPA navigation; set to "false" for full-page navigation. */
+    get history(): string;
+    set items(val: any);
+    /** Navigation items as a JSON array. */
+    get items(): any;
+    set position(val: "top" | "bottom");
+    /** Which edge of the viewport the dock anchors to. */
+    get position(): "top" | "bottom";
+    set size(val: string);
+    /** Controls icon size, label font size, and overall dock height. */
+    get size(): string;
+    /** Rebuilds the shadow DOM. */
+    render(): void;
+    _buildBar(): HTMLElement;
+    _buildItem(item: any): HTMLElement;
+    _buildStyles(): HTMLStyleElement;
+    _handleItemClick(item: any): void;
+    _setupBreakpoint(): void;
+    _setupItemKeyboard(bar: any): void;
+    _teardownBreakpoint(): void;
+}

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

@@ -0,0 +1,32 @@
+export class YumeDock extends HTMLElement {
+    static get observedAttributes(): string[];
+    _mediaQuery: MediaQueryList;
+    _onMediaChange(e: any): void;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(name: any, oldValue: any, newValue: any): void;
+    set breakpoint(val: number);
+    /** Viewport width below which dock is visible (px). When omitted, always visible. */
+    get breakpoint(): number;
+    set history(val: string);
+    /** Navigation mode. Omit for pushState SPA navigation; set to "false" for full-page navigation. */
+    get history(): string;
+    set items(val: any);
+    /** Navigation items as a JSON array. */
+    get items(): any;
+    set position(val: "top" | "bottom");
+    /** Which edge of the viewport the dock anchors to. */
+    get position(): "top" | "bottom";
+    set size(val: string);
+    /** Controls icon size, label font size, and overall dock height. */
+    get size(): string;
+    /** Rebuilds the shadow DOM. */
+    render(): void;
+    _buildBar(): HTMLElement;
+    _buildItem(item: any): HTMLElement;
+    _buildStyles(): HTMLStyleElement;
+    _handleItemClick(item: any): void;
+    _setupBreakpoint(): void;
+    _setupItemKeyboard(bar: any): void;
+    _teardownBreakpoint(): void;
+}

package/dist/components/y-dock.js

@@ -0,0 +1,546 @@
+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 YumeDock extends HTMLElement {
+    static get observedAttributes() {
+        return ["items", "position", "breakpoint", "size", "history"];
+    }
+
+    // -------------------------------------------------------------------------
+    // Lifecycle
+    // -------------------------------------------------------------------------
+
+    constructor() {
+        super();
+        this.attachShadow({ mode: "open" });
+        this._mediaQuery = null;
+        this._onMediaChange = this._onMediaChange.bind(this);
+    }
+
+    connectedCallback() {
+        if (!this.hasAttribute("position"))
+            this.setAttribute("position", "bottom");
+        if (!this.hasAttribute("size")) this.setAttribute("size", "medium");
+        if (!this.hasAttribute("role"))
+            this.setAttribute("role", "navigation");
+        if (!this.hasAttribute("aria-label"))
+            this.setAttribute("aria-label", "Dock navigation");
+        this.render();
+        this._teardownBreakpoint();
+        this._setupBreakpoint();
+    }
+
+    disconnectedCallback() {
+        this._teardownBreakpoint();
+    }
+
+    attributeChangedCallback(name, oldValue, newValue) {
+        if (oldValue === newValue) return;
+        if (name === "breakpoint") {
+            this._teardownBreakpoint();
+            this._setupBreakpoint();
+        }
+        this.render();
+    }
+
+    // -------------------------------------------------------------------------
+    // Getters / Setters
+    // -------------------------------------------------------------------------
+
+    /** Viewport width below which dock is visible (px). When omitted, always visible. */
+    get breakpoint() {
+        const val = this.getAttribute("breakpoint");
+        const num = Number(val);
+        return Number.isFinite(num) && num > 0 ? num : null;
+    }
+    set breakpoint(val) {
+        if (val == null) this.removeAttribute("breakpoint");
+        else this.setAttribute("breakpoint", String(val));
+    }
+
+    /** Navigation mode. Omit for pushState SPA navigation; set to "false" for full-page navigation. */
+    get history() {
+        return this.getAttribute("history");
+    }
+    set history(val) {
+        if (val == null) this.removeAttribute("history");
+        else this.setAttribute("history", val);
+    }
+
+    /** Navigation items as a JSON array. */
+    get items() {
+        try {
+            return JSON.parse(this.getAttribute("items") || "[]");
+        } catch {
+            return [];
+        }
+    }
+    set items(val) {
+        this.setAttribute("items", JSON.stringify(val));
+    }
+
+    /** Which edge of the viewport the dock anchors to. */
+    get position() {
+        const pos = this.getAttribute("position");
+        return pos === "top" ? "top" : "bottom";
+    }
+    set position(val) {
+        this.setAttribute("position", val === "top" ? "top" : "bottom");
+    }
+
+    /** Controls icon size, label font size, and overall dock height. */
+    get size() {
+        const sz = this.getAttribute("size");
+        return ["small", "medium", "large"].includes(sz) ? sz : "medium";
+    }
+    set size(val) {
+        this.setAttribute(
+            "size",
+            ["small", "medium", "large"].includes(val) ? val : "medium",
+        );
+    }
+
+    // -------------------------------------------------------------------------
+    // Public
+    // -------------------------------------------------------------------------
+
+    /** Rebuilds the shadow DOM. */
+    render() {
+        this.shadowRoot.innerHTML = "";
+        this.shadowRoot.appendChild(this._buildStyles());
+        this.shadowRoot.appendChild(this._buildBar());
+    }
+
+    // -------------------------------------------------------------------------
+    // Private
+    // -------------------------------------------------------------------------
+
+    _buildBar() {
+        const bar = createElement("div", { class: "bar", part: "bar" });
+
+        this.items.forEach((item) => bar.appendChild(this._buildItem(item)));
+        bar.appendChild(createElement("slot", {}));
+
+        this._setupItemKeyboard(bar);
+
+        return bar;
+    }
+
+    _buildItem(item) {
+        if (item.slot && this.querySelector(`[slot="${item.slot}"]`)) {
+            const wrapper = createElement("div", {
+                class: "item",
+                part: "item",
+                tabindex: "0",
+                role: "group",
+            });
+            wrapper.appendChild(createElement("slot", { name: item.slot }));
+            return wrapper;
+        }
+
+        const btn = createElement("button", {
+            class: "item",
+            part: "item",
+            "aria-label": item.name,
+        });
+
+        if (item.selected) btn.setAttribute("aria-current", "page");
+        if (item.href) btn.dataset.href = item.href;
+
+        const iconSize = { small: "medium", medium: "large", large: "x-large" }[
+            this.size
+        ];
+        const icon = createElement("y-icon", {
+            name: item.icon,
+            size: iconSize,
+        });
+        btn.appendChild(icon);
+
+        const label = createElement("span", { class: "item-label" }, [item.name]);
+        btn.appendChild(label);
+
+        btn.addEventListener("click", () => this._handleItemClick(item));
+
+        return btn;
+    }
+
+    _buildStyles() {
+        const style = document.createElement("style");
+        const pos = this.position;
+        const sz = this.size;
+        const heightVar = `var(--component-dock-height, var(--component-dock-height-${sz}))`;
+        const fontSize =
+            sz === "small" ? "10px" : sz === "large" ? "13px" : "11px";
+        style.textContent = `
+            :host {
+                display: block;
+                position: fixed;
+                ${pos === "top" ? "top: 0;" : "bottom: 0;"}
+                left: 0;
+                right: 0;
+                z-index: var(--component-dock-z-index, 8000);
+                ${
+                    pos === "bottom"
+                        ? "padding-bottom: env(safe-area-inset-bottom, 0px);"
+                        : "padding-top: env(safe-area-inset-top, 0px);"
+                }
+                background: var(--component-dock-background);
+                ${
+                    pos === "bottom"
+                        ? `border-top: var(--component-dock-border-width, 1px) solid var(--component-dock-border-color);`
+                        : `border-bottom: var(--component-dock-border-width, 1px) solid var(--component-dock-border-color);`
+                }
+            }
+            :host([hidden]) {
+                display: none !important;
+            }
+            .bar {
+                display: flex;
+                align-items: center;
+                justify-content: space-around;
+                height: ${heightVar};
+                position: relative;
+            }
+            .item {
+                display: flex;
+                flex-direction: column;
+                align-items: center;
+                justify-content: center;
+                gap: 2px;
+                background: none;
+                border: none;
+                padding: 4px 8px;
+                cursor: pointer;
+                color: var(--component-dock-color);
+                font-family: inherit;
+                font-size: ${fontSize};
+                min-width: 48px;
+                outline: none;
+                transition: color 0.15s ease;
+                -webkit-tap-highlight-color: transparent;
+            }
+            .item:focus-visible {
+                outline: 2px solid var(--component-dock-color-active);
+                outline-offset: -2px;
+                border-radius: 4px;
+            }
+            .item[aria-current="page"],
+            .item:hover {
+                color: var(--component-dock-color-active);
+            }
+            .item-label {
+                white-space: nowrap;
+                overflow: hidden;
+                text-overflow: ellipsis;
+                max-width: 64px;
+            }
+            ::slotted(*) {
+                display: flex;
+                flex-direction: column;
+                align-items: center;
+                justify-content: center;
+                gap: 2px;
+                color: var(--component-dock-color);
+                min-width: 48px;
+            }
+        `;
+        return style;
+    }
+
+    _handleItemClick(item) {
+        if (!item.href) return;
+
+        const event = new CustomEvent("navigate", {
+            detail: { href: item.href },
+            bubbles: true,
+            composed: true,
+            cancelable: true,
+        });
+
+        if (!this.dispatchEvent(event)) return;
+
+        if (this.history === "false") {
+            window.location.href = item.href;
+        } else {
+            window.history.pushState({}, "", item.href);
+            window.dispatchEvent(new PopStateEvent("popstate", { state: {} }));
+        }
+    }
+
+    _onMediaChange(e) {
+        this.hidden = !e.matches;
+    }
+
+    _setupBreakpoint() {
+        const bp = this.breakpoint;
+        if (bp == null) {
+            this.hidden = false;
+            return;
+        }
+
+        this._mediaQuery = window.matchMedia(`(max-width: ${bp}px)`);
+        this._mediaQuery.addEventListener("change", this._onMediaChange);
+        this.hidden = !this._mediaQuery.matches;
+    }
+
+    _setupItemKeyboard(bar) {
+        const slot = bar.querySelector("slot:not([name])");
+
+        const getItems = () => {
+            const shadowItems = Array.from(bar.querySelectorAll(".item"));
+            const slottedItems = slot
+                ? Array.from(slot.assignedElements({ flatten: true }))
+                : [];
+            return [...shadowItems, ...slottedItems];
+        };
+
+        bar.addEventListener("keydown", (e) => {
+            const items = getItems();
+            const path = e.composedPath();
+            const idx = items.findIndex(
+                (item) => item === e.target || path.includes(item),
+            );
+            if (idx === -1) return;
+
+            if (e.key === "ArrowRight") {
+                e.preventDefault();
+                items[(idx + 1) % items.length].focus();
+            } else if (e.key === "ArrowLeft") {
+                e.preventDefault();
+                items[(idx - 1 + items.length) % items.length].focus();
+            } else if (e.key === "Enter" || e.key === " ") {
+                e.preventDefault();
+                items[idx].click();
+            }
+        });
+    }
+
+    _teardownBreakpoint() {
+        if (this._mediaQuery) {
+            this._mediaQuery.removeEventListener("change", this._onMediaChange);
+            this._mediaQuery = null;
+        }
+    }
+}
+
+if (!customElements.get("y-dock")) {
+    customElements.define("y-dock", YumeDock);
+}
+
+export { YumeDock };