@incursa/ui-kit 1.6.1 → 1.8.0

package/dist/web-components/README.md

@@ -8,9 +8,11 @@ The CSS-first [`inc-*`](../../reference.html) class surface remains the canonica
 
 - Package entrypoint: `@incursa/ui-kit/web-components`
 - Style entrypoint: `@incursa/ui-kit/web-components/style.css`
+- Icon entrypoint: `@incursa/ui-kit/icons`
 - Built output: `dist/web-components/`
 - Package export: `./web-components` resolves to `dist/web-components/index.js`
 - Package export: `./web-components/style.css` resolves to `dist/web-components/style.css`
+- Package export: `./icons` resolves to `dist/icons/index.js`
 - Module boundary: `src/web-components/package.json` sets this subtree to `type: module`
 
 Load these entrypoints only when the consuming app wants the custom elements and their default look. CSS-only consumers should not pay for the runtime.
@@ -45,6 +47,8 @@ The runtime auto-defines the shipped elements on load. If a consumer needs expli
   The `IncElement` base class, including reflected attribute/property wiring and slot helpers.
 - [`registry.js`](registry.js)
   Idempotent registration helpers and the `IncWebComponents.registry` namespace.
+- [`../icons/index.js`](../icons/index.js)
+  Semantic Incursa icon names, default Lucide-backed rendering, and the global renderer override used by component fallbacks.
 - [`components/dom-helpers.js`](components/dom-helpers.js)
   Shared DOM helpers used by the action and collection modules.
 - [`controllers/focus.js`](controllers/focus.js)

package/dist/web-components/components/actions.js

@@ -1,3 +1,7 @@
+import {
+    normalizeIconName,
+    replaceIconContents,
+} from "../../icons/index.js";
 import {
     addClass,
     ensureNode,
@@ -24,6 +28,18 @@ const BUTTON_VARIANTS = new Set([
     "outline-info",
 ]);
 const BUTTON_SIZES = new Set(["sm", "lg", "micro"]);
+const ALERT_DEFAULT_ROLE_BY_TONE = new Map([
+    ["info", "status"],
+    ["secondary", "status"],
+]);
+const ALERT_ICON_BY_TONE = new Map([
+    ["success", "success"],
+    ["danger", "error"],
+    ["warning", "warning"],
+    ["info", "info"],
+    ["secondary", "info"],
+    ["primary", "info"],
+]);
 
 const HostElement = typeof HTMLElement === "undefined" ? class {} : HTMLElement;
 
@@ -35,6 +51,11 @@ function toBoolean(value, fallback = false) {
     return !FALSE_TOKENS.has(String(value).toLowerCase());
 }
 
+function toPositiveInt(value) {
+    const parsed = Number.parseInt(String(value ?? "").trim(), 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : null;
+}
+
 function emit(host, type, detail = {}, options = {}) {
     return host.dispatchEvent(new CustomEvent(type, {
         detail,
@@ -44,6 +65,29 @@ function emit(host, type, detail = {}, options = {}) {
     }));
 }
 
+function getDirectIconSlot(host) {
+    return Array.from(host.children || []).find((node) => (
+        node instanceof HTMLElement
+        && node.getAttribute("slot") === "icon"
+    )) || null;
+}
+
+function hasConsumerIcon(container) {
+    return Array.from(container.children || []).some((node) => (
+        node instanceof HTMLElement
+        && !node.hasAttribute("data-inc-generated-icon")
+    ));
+}
+
+function renderDecorativeIcon(container, name, options = {}) {
+    replaceIconContents(container, name, {
+        className: "inc-icon",
+        decorative: true,
+        size: options.size || 16,
+    });
+    container.hidden = false;
+}
+
 class IncElement extends HostElement {
     emit(type, detail = {}, options = {}) {
         return emit(this, type, detail, options);
@@ -52,7 +96,7 @@ class IncElement extends HostElement {
 
 export class IncButtonElement extends IncElement {
     static get observedAttributes() {
-        return ["tone", "variant", "size", "loading", "href", "type", "disabled", "label", "target", "rel", "download"];
+        return ["tone", "variant", "size", "loading", "href", "type", "disabled", "label", "target", "rel", "download", "icon"];
     }
 
     connectedCallback() {
@@ -157,6 +201,8 @@ export class IncButtonElement extends IncElement {
             this.removeLoadingSpinner(control);
         }
 
+        this.syncIcon(control);
+
         const label = this.getAttribute("label");
         if (label) {
             control.setAttribute("aria-label", label);
@@ -211,6 +257,53 @@ export class IncButtonElement extends IncElement {
 
         control.querySelectorAll(":scope > [data-inc-button-spinner]").forEach((node) => node.remove());
     }
+
+    syncIcon(control) {
+        if (!(control instanceof HTMLElement)) {
+            return;
+        }
+
+        const explicitIcon = normalizeIconName(this.getAttribute("icon"));
+        const inferredIcon = this.getAttribute("download") != null
+            ? "download"
+            : this.getAttribute("target") === "_blank"
+                ? "external-link"
+                : "";
+        const iconName = explicitIcon || inferredIcon;
+        let icon = control.querySelector(":scope > [data-inc-button-icon]");
+        const slotted = getDirectIconSlot(control);
+
+        if (!icon && (iconName || slotted)) {
+            icon = document.createElement("span");
+            icon.className = "inc-btn__icon";
+            icon.setAttribute("data-inc-button-icon", "true");
+            icon.setAttribute("aria-hidden", "true");
+            control.prepend(icon);
+        }
+
+        if (!(icon instanceof HTMLElement)) {
+            return;
+        }
+
+        if (slotted) {
+            slotted.removeAttribute("slot");
+            icon.replaceChildren(slotted);
+            icon.hidden = false;
+            return;
+        }
+
+        if (hasConsumerIcon(icon)) {
+            icon.hidden = false;
+            return;
+        }
+
+        if (iconName && iconName !== "none") {
+            renderDecorativeIcon(icon, iconName, { size: 16 });
+            return;
+        }
+
+        icon.remove();
+    }
 }
 
 export class IncButtonGroupElement extends IncElement {
@@ -292,7 +385,6 @@ export class IncCloseButtonElement extends IncElement {
     }
 
     connectedCallback() {
-        addClass(this, "inc-close-button");
         this.sync();
     }
 
@@ -303,7 +395,7 @@ export class IncCloseButtonElement extends IncElement {
     }
 
     sync() {
-        addClass(this, "inc-close-button");
+        this.classList.remove("inc-close-button", "inc-close-button--white");
         this.setAttribute("part", "close-button");
         const control = this.ensureControl();
         const variant = normalizeToken(this.getAttribute("variant"));
@@ -316,9 +408,7 @@ export class IncCloseButtonElement extends IncElement {
 
         control.type = "button";
         control.setAttribute("aria-label", this.getAttribute("label") || "Close");
-        if (!control.childNodes.length) {
-            control.textContent = "×";
-        }
+        control.textContent = "";
     }
 
     ensureControl() {
@@ -344,7 +434,7 @@ export class IncCloseButtonElement extends IncElement {
 
 export class IncAlertElement extends IncElement {
     static get observedAttributes() {
-        return ["tone", "variant", "dismissible", "dismiss-label"];
+        return ["tone", "variant", "dismissible", "dismiss-label", "timeout", "icon"];
     }
 
     connectedCallback() {
@@ -354,6 +444,7 @@ export class IncAlertElement extends IncElement {
     }
 
     disconnectedCallback() {
+        this.stopDismissTimer();
         if (this._boundClick) {
             this.removeEventListener("click", this._boundClick);
         }
@@ -377,7 +468,7 @@ export class IncAlertElement extends IncElement {
             }
 
             event.preventDefault();
-            this.hide();
+            this.dismiss("manual");
         };
 
         this.addEventListener("click", this._boundClick);
@@ -391,6 +482,7 @@ export class IncAlertElement extends IncElement {
         const tone = normalizeToken(this.getAttribute("tone") || this.getAttribute("variant")) || "info";
         const resolvedTone = BADGE_TONES.has(tone) ? tone : "info";
         this.classList.add(`inc-alert--${resolvedTone}`);
+        this.syncIcon(resolvedTone);
 
         if (toBoolean(this.getAttribute("dismissible"))) {
             this.classList.add("inc-alert--dismissible");
@@ -400,12 +492,25 @@ export class IncAlertElement extends IncElement {
         }
 
         if (!this.hasAttribute("role")) {
-            this.setAttribute("role", resolvedTone === "info" || resolvedTone === "secondary" ? "status" : "alert");
+            this.setAttribute("role", ALERT_DEFAULT_ROLE_BY_TONE.get(resolvedTone) || "alert");
         }
         if (!this.hasAttribute("aria-live")) {
             this.setAttribute("aria-live", this.getAttribute("role") === "alert" ? "assertive" : "polite");
         }
         this.setAttribute("aria-atomic", "true");
+
+        const timeoutMs = toPositiveInt(this.getAttribute("timeout"));
+        if (timeoutMs) {
+            this.ensureProgressBar();
+            if (!this.hidden && this.getAttribute("aria-hidden") !== "true") {
+                this.startDismissTimer(timeoutMs);
+            } else {
+                this.stopDismissTimer();
+            }
+        } else {
+            this.stopDismissTimer();
+            this.removeProgressBar();
+        }
     }
 
     ensureDismissButton() {
@@ -420,9 +525,7 @@ export class IncAlertElement extends IncElement {
         button.className = "inc-close-button";
         button.setAttribute("part", "dismiss");
         button.setAttribute("aria-label", this.getAttribute("dismiss-label") || "Dismiss alert");
-        if (!button.childNodes.length) {
-            button.textContent = "×";
-        }
+        button.textContent = "";
         return button;
     }
 
@@ -430,19 +533,125 @@ export class IncAlertElement extends IncElement {
         this.querySelectorAll(":scope > [data-inc-alert-dismiss]").forEach((node) => node.remove());
     }
 
-    hide() {
+    ensureProgressBar() {
+        let progress = this.querySelector(":scope > .inc-alert__progress");
+        if (!progress) {
+            progress = document.createElement("div");
+            progress.className = "inc-alert__progress";
+            progress.setAttribute("part", "progress");
+            progress.setAttribute("aria-hidden", "true");
+            this.append(progress);
+        }
+
+        return progress;
+    }
+
+    removeProgressBar() {
+        this.querySelectorAll(":scope > .inc-alert__progress").forEach((node) => node.remove());
+    }
+
+    syncIcon(tone) {
+        const explicitIcon = normalizeIconName(this.getAttribute("icon"));
+        const iconName = explicitIcon || ALERT_ICON_BY_TONE.get(tone) || "info";
+        let icon = this.querySelector(":scope > .inc-alert__icon");
+        const slotted = getDirectIconSlot(this);
+
+        if (!icon && (iconName !== "none" || slotted)) {
+            icon = document.createElement("span");
+            icon.className = "inc-alert__icon";
+            icon.setAttribute("part", "icon");
+            icon.setAttribute("aria-hidden", "true");
+            this.prepend(icon);
+        }
+
+        if (!(icon instanceof HTMLElement)) {
+            return;
+        }
+
+        if (slotted) {
+            slotted.removeAttribute("slot");
+            icon.replaceChildren(slotted);
+            icon.hidden = false;
+            return;
+        }
+
+        if (hasConsumerIcon(icon)) {
+            icon.hidden = false;
+            return;
+        }
+
+        if (iconName === "none") {
+            icon.remove();
+            return;
+        }
+
+        renderDecorativeIcon(icon, iconName, { size: 18 });
+    }
+
+    startDismissTimer(timeoutMs) {
+        const progress = this.ensureProgressBar();
+        this.stopDismissTimer();
+        this._dismissTimeoutMs = timeoutMs;
+        this._dismissStartedAt = performance.now();
+
+        const tick = (now) => {
+            if (this.hidden || this.getAttribute("aria-hidden") === "true") {
+                this.stopDismissTimer();
+                return;
+            }
+
+            const elapsed = Math.max(0, now - this._dismissStartedAt);
+            const remaining = Math.max(0, timeoutMs - elapsed);
+            const ratio = timeoutMs > 0 ? remaining / timeoutMs : 0;
+            progress.style.transform = `scaleX(${ratio})`;
+
+            if (remaining <= 0) {
+                this.dismiss("timeout");
+                return;
+            }
+
+            this._dismissFrame = window.requestAnimationFrame(tick);
+        };
+
+        progress.style.transform = "scaleX(1)";
+        this._dismissFrame = window.requestAnimationFrame(tick);
+    }
+
+    stopDismissTimer() {
+        if (this._dismissFrame) {
+            window.cancelAnimationFrame(this._dismissFrame);
+            this._dismissFrame = 0;
+        }
+    }
+
+    dismiss(reason = "manual") {
+        this.hide(reason);
+    }
+
+    hide(reason = "manual") {
+        this.stopDismissTimer();
         this.hidden = true;
         this.setAttribute("aria-hidden", "true");
-        this.emit("dismiss", { hidden: true });
+        this.emit("dismiss", { hidden: true, reason });
     }
 }
 
 export class IncEmptyStateElement extends IncElement {
+    static get observedAttributes() {
+        return ["icon"];
+    }
+
     connectedCallback() {
         addClass(this, "inc-empty-state");
         this.sync();
     }
 
+    attributeChangedCallback() {
+        if (this.isConnected) {
+            this.sync();
+        }
+    }
+
     sync() {
         addClass(this, "inc-empty-state");
         this.setAttribute("part", "empty-state content icon body actions");
@@ -496,6 +705,20 @@ export class IncEmptyStateElement extends IncElement {
 
             body.append(node);
         });
+
+        if (hasConsumerIcon(icon)) {
+            icon.hidden = false;
+            return;
+        }
+
+        const iconName = normalizeIconName(this.getAttribute("icon")) || "empty";
+        if (iconName === "none") {
+            icon.replaceChildren();
+            icon.hidden = true;
+            return;
+        }
+
+        renderDecorativeIcon(icon, iconName, { size: 34 });
     }
 }
 

package/dist/web-components/components/feedback.js

@@ -1,7 +1,30 @@
+import {
+    incIconNames,
+    normalizeIconName,
+    replaceIconContents,
+} from "../../icons/index.js";
+
 const THEME_MODES = ["light", "dark", "system"];
 const DEFAULT_THEME_STORAGE_KEY = "inc-theme-mode";
 const BADGE_TONES = new Set(["primary", "secondary", "success", "danger", "warning", "info"]);
 const SPINNER_VARIANTS = new Set(["border", "grow"]);
+const ICON_NAME_SET = new Set(incIconNames);
+const STATE_ICON_BY_VARIANT = new Map([
+    ["empty", "empty"],
+    ["results", "no-results"],
+    ["loading", "loading"],
+    ["error", "error"],
+    ["danger", "error"],
+    ["warning", "warning"],
+    ["success", "success"],
+    ["info", "info"],
+]);
+const STATE_ICON_BY_STATUS = new Map([
+    ["+", "empty"],
+    ["?", "no-results"],
+    ["!", "error"],
+    ["...", "loading"],
+]);
 const HostElement = typeof HTMLElement === "undefined" ? class {} : HTMLElement;
 const themeSubscribers = new Set();
 
@@ -38,6 +61,33 @@ function normalizeToken(value) {
     return String(value ?? "").trim().toLowerCase();
 }
 
+function resolveStateIconName(icon, status, variant) {
+    const explicitIcon = normalizeIconName(icon);
+    if (explicitIcon) {
+        return explicitIcon;
+    }
+
+    const normalizedStatus = normalizeIconName(status);
+    if (STATE_ICON_BY_STATUS.has(String(status || "").trim())) {
+        return STATE_ICON_BY_STATUS.get(String(status || "").trim());
+    }
+
+    if (ICON_NAME_SET.has(normalizedStatus)) {
+        return normalizedStatus;
+    }
+
+    return STATE_ICON_BY_VARIANT.get(normalizeToken(variant)) || "info";
+}
+
+function renderDecorativeIcon(container, name, size = 18) {
+    replaceIconContents(container, name, {
+        className: "inc-icon",
+        decorative: true,
+        size,
+    });
+    container.hidden = false;
+}
+
 function getSystemTheme() {
     if (!window.matchMedia) {
         return "light";
@@ -198,7 +248,7 @@ function formatRemaining(totalSeconds) {
 }
 
 export class IncStatePanel extends HostElement {
-    static observedAttributes = ["tone", "variant", "title", "body", "status", "open"];
+    static observedAttributes = ["tone", "variant", "title", "body", "status", "icon", "open"];
 
     #fallback = null;
     #appliedVariantClass = "";
@@ -238,6 +288,7 @@ export class IncStatePanel extends HostElement {
         actions.className = "inc-state-panel__actions";
 
         icon.setAttribute("part", "icon");
+        icon.setAttribute("aria-hidden", "true");
         title.setAttribute("part", "title");
         body.setAttribute("part", "body");
         actions.setAttribute("part", "actions");
@@ -274,11 +325,19 @@ export class IncStatePanel extends HostElement {
         const title = this.getAttribute("title") || "";
         const body = this.getAttribute("body") || "";
         const status = this.getAttribute("status") || "";
+        const iconName = resolveStateIconName(this.getAttribute("icon"), status, nextVariant);
 
         this.#fallback.title.textContent = title;
         this.#fallback.body.textContent = body;
-        this.#fallback.icon.textContent = status;
-        this.#fallback.icon.hidden = !status;
+        if (iconName === "none") {
+            this.#fallback.icon.replaceChildren();
+            this.#fallback.icon.hidden = true;
+        } else if (ICON_NAME_SET.has(iconName)) {
+            renderDecorativeIcon(this.#fallback.icon, iconName, 22);
+        } else {
+            this.#fallback.icon.textContent = status;
+            this.#fallback.icon.hidden = !status;
+        }
         this.#fallback.actions.hidden = true;
     }
 
@@ -677,6 +736,10 @@ export class IncAutoRefresh extends HostElement {
         }
 
         this.innerHTML = `
+<button type="button" class="inc-auto-refresh__toggle inc-btn inc-btn--outline-secondary inc-btn--micro" part="toggle">
+  <span class="inc-auto-refresh__toggle-icon" aria-hidden="true"></span>
+  <span class="inc-auto-refresh__toggle-text"></span>
+</button>
 <span class="inc-auto-refresh__countdown" part="countdown">
   <span class="inc-auto-refresh__label" part="label"></span>
   <span class="inc-auto-refresh__value" part="value"></span>
@@ -684,10 +747,6 @@ export class IncAutoRefresh extends HostElement {
 <span class="inc-auto-refresh__status" part="status" hidden>
   <span class="inc-auto-refresh__status-text"></span>
 </span>
-<button type="button" class="inc-auto-refresh__toggle inc-btn inc-btn--outline-secondary inc-btn--micro" part="toggle">
-  <span class="inc-auto-refresh__toggle-icon" aria-hidden="true"></span>
-  <span class="inc-auto-refresh__toggle-text"></span>
-</button>
         `.trim();
 
         this.#parts = this.#getParts();
@@ -701,6 +760,7 @@ export class IncAutoRefresh extends HostElement {
             status: this.querySelector(".inc-auto-refresh__status"),
             statusText: this.querySelector(".inc-auto-refresh__status-text"),
             toggle: this.querySelector(".inc-auto-refresh__toggle"),
+            toggleIcon: this.querySelector(".inc-auto-refresh__toggle-icon"),
             toggleText: this.querySelector(".inc-auto-refresh__toggle-text"),
         };
     }
@@ -861,6 +921,10 @@ export class IncAutoRefresh extends HostElement {
         if (this.#parts.toggleText) {
             this.#parts.toggleText.textContent = actionLabel;
         }
+
+        if (this.#parts.toggleIcon instanceof HTMLElement) {
+            renderDecorativeIcon(this.#parts.toggleIcon, this.#isPaused ? "play" : "pause", 16);
+        }
     }
 
     #stop() {