@incursa/ui-kit 1.7.0 → 1.9.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)
@@ -67,6 +71,8 @@ The runtime auto-defines the shipped elements on load. If a consumer needs expli
   Button, button-group, button-toolbar, close-button, alert, and empty-state custom elements.
 - [`components/collections.js`](components/collections.js)
   List-group, key-value-grid, and key-value custom elements.
+- [`components/visualizations.js`](components/visualizations.js)
+  D3-backed sparkline custom element and small path/data helpers.
 - [`components/overlays.js`](components/overlays.js)
   Disclosure, dialog, and drawer custom elements.
 - [`index.js`](index.js)
@@ -82,6 +88,7 @@ The Web Component layer should mirror the current CSS kit, not reinterpret it.
 - Form wrappers should keep native controls native.
 - Navigation components should reflect keyboard and focus state in the DOM.
 - Feedback and status shells should announce state accessibly, badge/spinner atoms should standardize the common tone and loading defaults, and action/detail plus collection hosts should keep buttons, alerts, list groups, and description-list pairs declarative without inventing a second styling vocabulary.
+- Visualization components should stay compact, accessible, and evidence-supporting. Use D3 for geometry and scales, not DOM mutation.
 - Overlays should prefer native `<details>` and `<dialog>` behavior when that satisfies the contract.
 - Tables, data presentation, utility atoms, and the remaining presentation-only surfaces should remain CSS-first until the component contract is explicit and worth the runtime cost.
 

package/dist/web-components/RUNTIME-NOTES.md

@@ -12,6 +12,7 @@ The runtime defines the approved v1 host family set:
 - feedback and status: `inc-state-panel`, `inc-live-region`, `inc-auto-refresh`, `inc-theme-switcher`, `inc-badge`, `inc-spinner`
 - actions and detail shells: `inc-button`, `inc-button-group`, `inc-button-toolbar`, `inc-close-button`, `inc-alert`, `inc-empty-state`
 - collections: `inc-list-group`, `inc-key-value-grid`, `inc-key-value`
+- data visualization: `inc-sparkline`
 - overlays: `inc-disclosure`, `inc-dialog`, `inc-drawer`
 
 ## Contract shape
@@ -28,6 +29,7 @@ The runtime defines the approved v1 host family set:
   - `components/feedback.js`
   - `components/actions.js`
   - `components/collections.js`
+  - `components/visualizations.js`
   - `components/overlays.js`
 - Public registration API is idempotent:
   - `window.IncWebComponents.defineAll()`

package/dist/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 });
     }
 }
 

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

@@ -1,15 +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 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();
+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();
 
@@ -46,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";
@@ -206,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 = "";
@@ -246,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");
@@ -282,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;
     }
 
@@ -872,7 +923,7 @@ export class IncAutoRefresh extends HostElement {
         }
 
         if (this.#parts.toggleIcon instanceof HTMLElement) {
-            this.#parts.toggleIcon.innerHTML = this.#isPaused ? AUTO_REFRESH_PLAY_ICON : AUTO_REFRESH_PAUSE_ICON;
+            renderDecorativeIcon(this.#parts.toggleIcon, this.#isPaused ? "play" : "pause", 16);
         }
     }