@incursa/ui-kit 1.7.0 → 1.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@incursa/ui-kit",
-  "version": "1.7.0",
+  "version": "1.9.0",
   "private": false,
   "description": "Reusable UI kit for data-heavy business applications.",
   "keywords": [
@@ -33,6 +33,9 @@
       "style": "./dist/web-components/style.css",
       "default": "./dist/web-components/index.js"
     },
+    "./icons": {
+      "default": "./dist/icons/index.js"
+    },
     "./web-components/style.css": "./dist/web-components/style.css",
     "./dist/inc-design-language.css": "./dist/inc-design-language.css",
     "./dist/inc-design-language.min.css": "./dist/inc-design-language.min.css",
@@ -52,11 +55,12 @@
   "scripts": {
     "build:css": "sass --load-path=node_modules --quiet-deps --silence-deprecation=import src/inc-design-language.scss dist/inc-design-language.css --style=expanded",
     "build:css:min": "sass --load-path=node_modules --quiet-deps --silence-deprecation=import src/inc-design-language.scss dist/inc-design-language.min.css --style=compressed",
-    "build:js": "node -e \"require('fs').copyFileSync('src/inc-design-language.js', 'dist/inc-design-language.js')\"",
+    "build:icons": "node scripts/build-icons.mjs",
+    "build:js": "esbuild src/inc-design-language.js --bundle --format=iife --platform=browser --outfile=dist/inc-design-language.js",
     "build:wc": "node scripts/build-web-components.mjs",
     "build:mcp:manifests": "node scripts/generate-mcp.mjs",
     "build:mcp": "node scripts/build-mcp.mjs",
-    "build": "npm run build:css && npm run build:css:min && npm run build:js && npm run build:wc && npm run build:mcp",
+    "build": "npm run build:icons && npm run build:css && npm run build:css:min && npm run build:js && npm run build:wc && npm run build:mcp",
     "test:browser:install": "playwright install chromium",
     "test:browser": "playwright test",
     "test:mcp": "node --test tests/mcp/transport.test.mjs tests/mcp/search.test.mjs tests/mcp/installation.test.mjs tests/mcp/markup.test.mjs tests/mcp/freshness.test.mjs",
@@ -70,6 +74,12 @@
     "pack:tarball": "npm pack",
     "package": "npm run build && npm run smoke && npm run pack:tarball"
   },
+  "dependencies": {
+    "d3-array": "^3.2.4",
+    "d3-scale": "^4.0.2",
+    "d3-shape": "^3.2.0",
+    "lucide": "^1.17.0"
+  },
   "devDependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@playwright/test": "^1.58.2",

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;
         }
     }
 
@@ -3363,6 +3394,100 @@ dialog.inc-native-dialog.inc-native-dialog--drawer .inc-native-dialog__body {
     }
 }
 
+.inc-sparkline {
+    --inc-sparkline-stroke: var(--inc-text-secondary);
+    --inc-sparkline-fill: rgba(var(--inc-text-secondary-rgb), 0.12);
+    --inc-sparkline-marker: var(--inc-sparkline-stroke);
+    --inc-sparkline-reference: rgba(var(--inc-text-muted-rgb), 0.68);
+    --inc-sparkline-muted: rgba(var(--inc-text-muted-rgb), 0.54);
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    inline-size: var(--inc-sparkline-width, 7.5rem);
+    block-size: var(--inc-sparkline-height, 2rem);
+    min-inline-size: 1rem;
+    min-block-size: 1rem;
+    vertical-align: middle;
+    color: var(--inc-sparkline-stroke);
+    contain: paint;
+
+    &--tone-positive {
+        --inc-sparkline-stroke: var(--bs-success);
+        --inc-sparkline-fill: rgba(var(--bs-success-rgb), 0.16);
+        --inc-sparkline-marker: var(--bs-success-text-emphasis);
+    }
+
+    &--tone-negative {
+        --inc-sparkline-stroke: var(--bs-danger);
+        --inc-sparkline-fill: rgba(var(--bs-danger-rgb), 0.14);
+        --inc-sparkline-marker: var(--bs-danger-text-emphasis);
+    }
+
+    &--tone-muted {
+        --inc-sparkline-stroke: var(--inc-text-muted);
+        --inc-sparkline-fill: rgba(var(--inc-text-muted-rgb), 0.1);
+        --inc-sparkline-marker: var(--inc-text-secondary);
+    }
+
+    &--tone-accent {
+        --inc-sparkline-stroke: var(--bs-primary);
+        --inc-sparkline-fill: rgba(var(--bs-primary-rgb), 0.14);
+        --inc-sparkline-marker: var(--bs-primary);
+    }
+
+    &__svg {
+        display: block;
+        inline-size: 100%;
+        block-size: 100%;
+        overflow: visible;
+    }
+
+    &__line,
+    &__empty-line {
+        fill: none;
+        stroke: var(--inc-sparkline-stroke);
+        stroke-width: 1.6;
+        stroke-linecap: round;
+        stroke-linejoin: round;
+    }
+
+    &__area {
+        fill: var(--inc-sparkline-fill);
+        stroke: none;
+    }
+
+    &__bar {
+        fill: var(--inc-sparkline-stroke);
+        opacity: 0.82;
+    }
+
+    &__marker {
+        fill: var(--inc-sparkline-marker);
+        stroke: var(--inc-surface-primary);
+        stroke-width: 1.5;
+    }
+
+    &__reference {
+        stroke: var(--inc-sparkline-reference);
+        stroke-width: 1;
+        stroke-dasharray: 3 3;
+    }
+
+    &__empty-line {
+        stroke: var(--inc-sparkline-muted);
+        stroke-dasharray: 2 4;
+    }
+
+    &__empty {
+        fill: var(--inc-text-muted);
+        font-family: $font-family-sans-serif;
+        font-size: 0.625rem;
+        font-weight: 600;
+        letter-spacing: 0;
+        pointer-events: none;
+    }
+}
+
 .inc-alert-container {
     @extend .container-xxl;
     position: relative;
@@ -4644,6 +4769,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)
@@ -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/src/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()`