@incursa/ui-kit 1.7.0 → 1.8.0

package/src/icons/index.js

@@ -0,0 +1,229 @@
+import createLucideElement from "lucide/dist/esm/createElement.mjs";
+import CircleCheck from "lucide/dist/esm/icons/circle-check.mjs";
+import CircleHelp from "lucide/dist/esm/icons/circle-question-mark.mjs";
+import CircleX from "lucide/dist/esm/icons/circle-x.mjs";
+import Download from "lucide/dist/esm/icons/download.mjs";
+import ExternalLink from "lucide/dist/esm/icons/external-link.mjs";
+import FileText from "lucide/dist/esm/icons/file-text.mjs";
+import FolderPlus from "lucide/dist/esm/icons/folder-plus.mjs";
+import Info from "lucide/dist/esm/icons/info.mjs";
+import Lock from "lucide/dist/esm/icons/lock.mjs";
+import Pause from "lucide/dist/esm/icons/pause.mjs";
+import Play from "lucide/dist/esm/icons/play.mjs";
+import RefreshCw from "lucide/dist/esm/icons/refresh-cw.mjs";
+import SearchX from "lucide/dist/esm/icons/search-x.mjs";
+import Settings from "lucide/dist/esm/icons/settings.mjs";
+import ShieldCheck from "lucide/dist/esm/icons/shield-check.mjs";
+import TriangleAlert from "lucide/dist/esm/icons/triangle-alert.mjs";
+import Upload from "lucide/dist/esm/icons/upload.mjs";
+
+const ICON_NODES = Object.freeze({
+    info: Info,
+    help: CircleHelp,
+    success: CircleCheck,
+    warning: TriangleAlert,
+    error: CircleX,
+    upload: Upload,
+    document: FileText,
+    download: Download,
+    settings: Settings,
+    "external-link": ExternalLink,
+    empty: FolderPlus,
+    "no-results": SearchX,
+    loading: RefreshCw,
+    lock: Lock,
+    pause: Pause,
+    play: Play,
+    permission: ShieldCheck,
+});
+
+const ICON_NAMES = Object.freeze(Object.keys(ICON_NODES));
+const DEFAULT_SIZE = 16;
+
+function getNamespace() {
+    if (typeof globalThis === "undefined") {
+        return null;
+    }
+
+    const root = globalThis.IncWebComponents || (globalThis.IncWebComponents = {});
+    const icons = root.icons || (root.icons = {});
+
+    if (!icons.names) {
+        icons.names = ICON_NAMES;
+    }
+
+    if (!icons.defaultRenderer) {
+        icons.defaultRenderer = renderDefaultIcon;
+    }
+
+    if (!icons.render) {
+        icons.render = renderIncIcon;
+    }
+
+    if (!icons.setRenderer) {
+        icons.setRenderer = setIconRenderer;
+    }
+
+    return icons;
+}
+
+function normalizeIconName(name) {
+    return String(name || "")
+        .trim()
+        .toLowerCase()
+        .replace(/[_\s]+/g, "-");
+}
+
+function normalizeSize(value) {
+    const parsed = Number.parseFloat(value);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_SIZE;
+}
+
+function buildIconAttributes(name, options = {}) {
+    const size = normalizeSize(options.size);
+    const className = options.className || "inc-icon";
+    const attrs = {
+        width: size,
+        height: size,
+        "data-inc-icon": name,
+        class: className,
+        focusable: "false",
+    };
+
+    if (options.decorative !== false) {
+        attrs["aria-hidden"] = "true";
+    } else {
+        attrs.role = "img";
+        attrs["aria-label"] = options.label || name;
+    }
+
+    return attrs;
+}
+
+function renderDefaultIcon(name, options = {}) {
+    const normalizedName = normalizeIconName(name);
+    const iconNode = ICON_NODES[normalizedName] || ICON_NODES.info;
+
+    if (typeof document === "undefined") {
+        return "";
+    }
+
+    return createLucideElement(iconNode, buildIconAttributes(normalizedName, options));
+}
+
+function coerceIconResult(result) {
+    if (!result || typeof document === "undefined") {
+        return null;
+    }
+
+    if (result instanceof Node) {
+        return result;
+    }
+
+    if (typeof result === "string") {
+        const template = document.createElement("template");
+        template.innerHTML = result.trim();
+        return template.content.firstElementChild || null;
+    }
+
+    return null;
+}
+
+function getIconRenderer() {
+    const namespace = getNamespace();
+    return typeof namespace?.renderer === "function"
+        ? namespace.renderer
+        : renderDefaultIcon;
+}
+
+function setIconRenderer(renderer) {
+    const namespace = getNamespace();
+    if (!namespace) {
+        return null;
+    }
+
+    if (renderer == null) {
+        delete namespace.renderer;
+        return null;
+    }
+
+    if (typeof renderer !== "function") {
+        throw new TypeError("Inc icon renderer must be a function.");
+    }
+
+    namespace.renderer = renderer;
+    return renderer;
+}
+
+function renderIncIcon(name, options = {}) {
+    const normalizedName = normalizeIconName(name) || "info";
+    const renderer = getIconRenderer();
+    const rendered = renderer(normalizedName, options);
+    const icon = coerceIconResult(rendered) || coerceIconResult(renderDefaultIcon(normalizedName, options));
+
+    if (icon instanceof Element && options.decorative !== false) {
+        icon.setAttribute("aria-hidden", "true");
+        icon.removeAttribute("aria-label");
+        icon.removeAttribute("role");
+    }
+
+    return icon;
+}
+
+function replaceIconContents(container, name, options = {}) {
+    if (!(container instanceof Element)) {
+        return null;
+    }
+
+    container.replaceChildren();
+    const icon = renderIncIcon(name, options);
+    if (icon) {
+        icon.setAttribute("data-inc-generated-icon", "true");
+        icon.setAttribute("data-inc-icon-upgraded", "true");
+        container.append(icon);
+    }
+
+    return icon;
+}
+
+function upgradeIconPlaceholders(root = typeof document !== "undefined" ? document : null) {
+    if (!root || typeof root.querySelectorAll !== "function") {
+        return [];
+    }
+
+    const upgraded = [];
+    root.querySelectorAll("[data-inc-icon]").forEach((node) => {
+        if (!(node instanceof Element)) {
+            return;
+        }
+
+        const name = node.getAttribute("data-inc-icon");
+        if (!name || node.hasAttribute("data-inc-icon-upgraded") || node.hasAttribute("data-inc-generated-icon")) {
+            return;
+        }
+
+        replaceIconContents(node, name, {
+            className: node.getAttribute("data-inc-icon-class") || "inc-icon",
+            decorative: node.getAttribute("aria-hidden") !== "false",
+            label: node.getAttribute("aria-label") || undefined,
+            size: node.getAttribute("data-inc-icon-size") || undefined,
+        });
+        node.setAttribute("data-inc-icon-upgraded", "true");
+        upgraded.push(node);
+    });
+
+    return upgraded;
+}
+
+getNamespace();
+
+export {
+    ICON_NAMES as incIconNames,
+    getIconRenderer,
+    normalizeIconName,
+    renderDefaultIcon,
+    renderIncIcon,
+    replaceIconContents,
+    setIconRenderer,
+    upgradeIconPlaceholders,
+};

package/src/icons/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/src/inc-design-language.js

@@ -1,3 +1,8 @@
+import {
+    replaceIconContents,
+    upgradeIconPlaceholders,
+} from "./icons/index.js";
+
 (function () {
     "use strict";
 
@@ -12,6 +17,7 @@
         themeLabel: "[data-inc-theme-label]",
         themeSwitcher: "[data-inc-theme-switcher], details.inc-theme-switcher",
         nativeDialogOpen: "[data-inc-native-dialog-open]",
+        icon: "[data-inc-icon]",
         autoRefresh: "[data-inc-auto-refresh]",
         autoRefreshToggle: '[data-inc-action="auto-refresh-toggle"]',
         fileExample: "[data-inc-file-example]",
@@ -1132,16 +1138,6 @@
         return `${minutes}m ${seconds}s`;
     }
 
-    const AUTO_REFRESH_PAUSE_ICON = `
-<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 16 16" fill="currentColor" aria-hidden="true">
-  <path d="M4 3h3v10H4zM9 3h3v10H9z"></path>
-</svg>`.trim();
-
-    const AUTO_REFRESH_PLAY_ICON = `
-<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 16 16" fill="currentColor" aria-hidden="true">
-  <path d="M4 3.5v9l8-4.5-8-4.5z"></path>
-</svg>`.trim();
-
     function getAutoRefreshParts(root) {
         const toggle = root.querySelector(".inc-auto-refresh__toggle");
 
@@ -1183,7 +1179,11 @@
         }
 
         if (parts.toggleIcon instanceof HTMLElement) {
-            parts.toggleIcon.innerHTML = isPaused ? AUTO_REFRESH_PLAY_ICON : AUTO_REFRESH_PAUSE_ICON;
+            replaceIconContents(parts.toggleIcon, isPaused ? "play" : "pause", {
+                className: "inc-icon",
+                decorative: true,
+                size: 16,
+            });
         }
     }
 
@@ -1848,6 +1848,7 @@
         initializeMenus();
         initializeCollapses();
         initializeTabs();
+        upgradeIconPlaceholders(document);
         initializeFileExamples();
         initializeAutoRefresh();
         attachEventHandlers();

package/src/inc-design-language.scss

@@ -448,6 +448,12 @@
 // Buttons, badges, alerts, and form primitives
 // -----------------------------------------------------------------------------
 
+.inc-icon {
+    display: block;
+    flex: 0 0 auto;
+    stroke: currentColor;
+}
+
 .inc-btn {
     @extend .btn;
     display: inline-flex;
@@ -457,6 +463,15 @@
     vertical-align: middle;
     transition: color 0.18s ease, background-color 0.18s ease, border-color 0.18s ease, box-shadow 0.18s ease;
 
+    &__icon {
+        display: inline-flex;
+        align-items: center;
+        justify-content: center;
+        width: 1rem;
+        height: 1rem;
+        flex: 0 0 auto;
+    }
+
     &--primary {
         @extend .btn-primary;
     }
@@ -736,6 +751,17 @@
         @extend .alert-dismissible;
     }
 
+    &__icon {
+        display: inline-flex;
+        align-items: center;
+        justify-content: center;
+        width: 1.125rem;
+        height: 1.125rem;
+        margin-inline-end: 0.5rem;
+        vertical-align: -0.2em;
+        color: currentColor;
+    }
+
     &__heading {
         @extend .alert-heading;
     }
@@ -1175,6 +1201,12 @@
         display: inline-flex;
         align-items: center;
         justify-content: center;
+
+        svg {
+            display: block;
+            width: 2.125rem;
+            height: 2.125rem;
+        }
     }
 
     &__form {
@@ -3238,7 +3270,6 @@ dialog.inc-native-dialog.inc-native-dialog--drawer .inc-native-dialog__body {
             display: block;
             width: 1rem;
             height: 1rem;
-            fill: currentColor;
         }
     }
 
@@ -4644,6 +4675,12 @@ body.inc-offcanvas-open {
         font-size: 1.25rem;
         font-weight: 700;
         flex: 0 0 auto;
+
+        svg {
+            display: block;
+            width: 1.375rem;
+            height: 1.375rem;
+        }
     }
 
     &__title {

package/src/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/src/web-components/components/actions.js

@@ -1,3 +1,7 @@
+import {
+    normalizeIconName,
+    replaceIconContents,
+} from "../../icons/index.js";
 import {
     addClass,
     ensureNode,
@@ -28,6 +32,14 @@ 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;
 
@@ -53,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);
@@ -61,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() {
@@ -166,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);
@@ -220,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 {
@@ -350,7 +434,7 @@ export class IncCloseButtonElement extends IncElement {
 
 export class IncAlertElement extends IncElement {
     static get observedAttributes() {
-        return ["tone", "variant", "dismissible", "dismiss-label", "timeout"];
+        return ["tone", "variant", "dismissible", "dismiss-label", "timeout", "icon"];
     }
 
     connectedCallback() {
@@ -398,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");
@@ -465,6 +550,44 @@ export class IncAlertElement extends IncElement {
         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();
@@ -514,11 +637,21 @@ export class IncAlertElement extends IncElement {
 }
 
 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");
@@ -572,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 });
     }
 }