@incursa/ui-kit 1.5.0 → 1.6.1

package/dist/web-components/README.md

@@ -45,6 +45,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.
+- [`components/dom-helpers.js`](components/dom-helpers.js)
+  Shared DOM helpers used by the action and collection modules.
 - [`controllers/focus.js`](controllers/focus.js)
   Shared focus utilities for focus trapping, focus restoration, and focusable-element discovery.
 - [`controllers/selection.js`](controllers/selection.js)
@@ -60,11 +62,15 @@ The runtime auto-defines the shipped elements on load. If a consumer needs expli
 - [`components/forms.js`](components/forms.js)
   Field wrappers, input groups, choice groups, read-only fields, and validation summary custom elements.
 - [`components/feedback.js`](components/feedback.js)
-  State panel, live-region, auto-refresh, and theme-switcher custom elements.
+  State panel, live-region, auto-refresh, badge, spinner, and theme-switcher custom elements.
+- [`components/actions.js`](components/actions.js)
+  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/overlays.js`](components/overlays.js)
   Disclosure, dialog, and drawer custom elements.
 - [`index.js`](index.js)
-  Additive package bootstrap that registers the shipped families and exposes the public namespace.
+  Thin package bootstrap that imports the family modules, registers the shipped families, and exposes the public namespace.
 
 As more families land, keep them in this same shape: small shared controllers plus family modules that register their public elements through the registry.
 
@@ -75,9 +81,9 @@ The Web Component layer should mirror the current CSS kit, not reinterpret it.
 - Layout primitives should stay composable and slot-driven.
 - 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.
+- 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.
 - Overlays should prefer native `<details>` and `<dialog>` behavior when that satisfies the contract.
-- Tables, data presentation, utility atoms, and other presentation-only surfaces should remain CSS-first until the component contract is explicit and worth the runtime cost.
+- 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.
 
 ## Maintenance Notes
 

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

@@ -9,20 +9,25 @@ The runtime defines the approved v1 host family set:
 - layouts and shells: `inc-app-shell`, `inc-page`, `inc-page-header`, `inc-section`, `inc-card`, `inc-summary-overview`, `inc-summary-block`, `inc-footer-bar`
 - navigation: `inc-navbar`, `inc-tabs`, `inc-user-menu`
 - forms and inputs: `inc-field`, `inc-input-group`, `inc-choice-group`, `inc-readonly-field`, `inc-validation-summary`
-- feedback and status: `inc-state-panel`, `inc-live-region`, `inc-auto-refresh`, `inc-theme-switcher`
+- 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`
 - overlays: `inc-disclosure`, `inc-dialog`, `inc-drawer`
 
 ## Contract shape
 
 - CSS-first is still canonical. Components reuse existing `inc-*` class contracts.
+- Badge and spinner hosts standardize the most common atomic status defaults while still reusing the same `inc-*` vocabulary, the action/detail hosts standardize repeated button, alert, and empty-state markup patterns, and the collection hosts standardize repeated list and key/value markup patterns.
 - Package consumers should pair `@incursa/ui-kit/web-components` with `@incursa/ui-kit/web-components/style.css` when they want the default look out of the box.
 - v1 stays light DOM first so current style selectors keep working.
 - Native primitives are used for disclosure/menu/dialog behavior where practical.
-- `index.js` is a thin bootstrap that registers family modules:
+- `index.js` is a thin bootstrap that registers family modules and the promoted action/detail and collection hosts:
   - `components/layout.js`
   - `components/navigation.js`
   - `components/forms.js`
   - `components/feedback.js`
+  - `components/actions.js`
+  - `components/collections.js`
   - `components/overlays.js`
 - Public registration API is idempotent:
   - `window.IncWebComponents.defineAll()`

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

@@ -0,0 +1,557 @@
+import {
+    addClass,
+    ensureNode,
+    moveChildNodes,
+    normalizeToken,
+    removeMatchingClasses,
+} from "./dom-helpers.js";
+
+const FALSE_TOKENS = new Set(["false", "0", "off", "no"]);
+const BADGE_TONES = new Set(["primary", "secondary", "success", "danger", "warning", "info"]);
+const BUTTON_VARIANTS = new Set([
+    "primary",
+    "secondary",
+    "success",
+    "danger",
+    "warning",
+    "info",
+    "link",
+    "outline-primary",
+    "outline-secondary",
+    "outline-success",
+    "outline-danger",
+    "outline-warning",
+    "outline-info",
+]);
+const BUTTON_SIZES = new Set(["sm", "lg", "micro"]);
+
+const HostElement = typeof HTMLElement === "undefined" ? class {} : HTMLElement;
+
+function toBoolean(value, fallback = false) {
+    if (value == null) {
+        return fallback;
+    }
+
+    return !FALSE_TOKENS.has(String(value).toLowerCase());
+}
+
+function emit(host, type, detail = {}, options = {}) {
+    return host.dispatchEvent(new CustomEvent(type, {
+        detail,
+        bubbles: options.bubbles !== false,
+        composed: options.composed !== false,
+        cancelable: options.cancelable === true,
+    }));
+}
+
+class IncElement extends HostElement {
+    emit(type, detail = {}, options = {}) {
+        return emit(this, type, detail, options);
+    }
+}
+
+export class IncButtonElement extends IncElement {
+    static get observedAttributes() {
+        return ["tone", "variant", "size", "loading", "href", "type", "disabled", "label", "target", "rel", "download"];
+    }
+
+    connectedCallback() {
+        addClass(this, "inc-button");
+        this.bindEvents();
+        this.sync();
+    }
+
+    disconnectedCallback() {
+        if (this._boundClick) {
+            this.removeEventListener("click", this._boundClick);
+        }
+    }
+
+    attributeChangedCallback() {
+        if (this.isConnected) {
+            this.sync();
+        }
+    }
+
+    bindEvents() {
+        if (this._boundClick) {
+            return;
+        }
+
+        this._boundClick = (event) => {
+            if (!this._control || !this.contains(this._control)) {
+                return;
+            }
+
+            const isBlocked = this._control.hasAttribute("aria-disabled") || this._control.classList.contains("is-loading");
+            if (!isBlocked || this._control.tagName !== "A") {
+                return;
+            }
+
+            event.preventDefault();
+            event.stopPropagation();
+        };
+
+        this.addEventListener("click", this._boundClick);
+    }
+
+    sync() {
+        addClass(this, "inc-button");
+        this.setAttribute("part", "button");
+        const control = this.ensureControl();
+        const variant = normalizeToken(this.getAttribute("variant") || this.getAttribute("tone")) || "secondary";
+        const resolvedVariant = BUTTON_VARIANTS.has(variant) ? variant : "secondary";
+        const size = normalizeToken(this.getAttribute("size"));
+        const loading = toBoolean(this.getAttribute("loading"));
+        const disabled = toBoolean(this.getAttribute("disabled")) || loading;
+
+        control.className = "inc-btn inc-button__control";
+        control.setAttribute("part", "control");
+        control.classList.add(`inc-btn--${resolvedVariant}`);
+        if (BUTTON_SIZES.has(size)) {
+            control.classList.add(`inc-btn--${size}`);
+        }
+        control.classList.toggle("is-loading", loading);
+
+        if (control.tagName === "BUTTON") {
+            control.type = this.getAttribute("type") || "button";
+            control.disabled = disabled;
+        } else {
+            control.setAttribute("href", this.getAttribute("href") || "#");
+
+            const target = this.getAttribute("target");
+            if (target) {
+                control.setAttribute("target", target);
+            } else {
+                control.removeAttribute("target");
+            }
+
+            const rel = this.getAttribute("rel");
+            if (rel) {
+                control.setAttribute("rel", rel);
+            } else {
+                control.removeAttribute("rel");
+            }
+
+            const download = this.getAttribute("download");
+            if (download != null) {
+                control.setAttribute("download", download);
+            } else {
+                control.removeAttribute("download");
+            }
+
+            if (disabled) {
+                control.setAttribute("aria-disabled", "true");
+                control.tabIndex = -1;
+            } else {
+                control.removeAttribute("aria-disabled");
+                control.removeAttribute("tabindex");
+            }
+        }
+
+        if (loading) {
+            control.setAttribute("aria-busy", "true");
+            this.ensureLoadingSpinner(control);
+        } else {
+            control.removeAttribute("aria-busy");
+            this.removeLoadingSpinner(control);
+        }
+
+        const label = this.getAttribute("label");
+        if (label) {
+            control.setAttribute("aria-label", label);
+        } else {
+            control.removeAttribute("aria-label");
+        }
+    }
+
+    ensureControl() {
+        const desiredTag = this.hasAttribute("href") ? "A" : "BUTTON";
+        const existing = this._control || this.querySelector(":scope > button.inc-button__control, :scope > a.inc-button__control");
+
+        if (existing && existing.tagName === desiredTag) {
+            this._control = existing;
+            return existing;
+        }
+
+        const control = document.createElement(desiredTag.toLowerCase());
+        if (desiredTag === "BUTTON") {
+            control.type = this.getAttribute("type") || "button";
+        }
+
+        if (existing) {
+            moveChildNodes(existing, control);
+            existing.replaceWith(control);
+        } else {
+            moveChildNodes(this, control);
+            this.append(control);
+        }
+
+        if (!control.childNodes.length) {
+            control.textContent = this.textContent || "";
+        }
+
+        this._control = control;
+        return control;
+    }
+
+    ensureLoadingSpinner(control) {
+        this.removeLoadingSpinner(control);
+        const spinner = document.createElement("span");
+        spinner.dataset.incButtonSpinner = "true";
+        spinner.className = "inc-spinner inc-spinner--border inc-spinner--border--sm";
+        spinner.setAttribute("aria-hidden", "true");
+        control.append(spinner);
+    }
+
+    removeLoadingSpinner(control) {
+        if (!(control instanceof HTMLElement)) {
+            return;
+        }
+
+        control.querySelectorAll(":scope > [data-inc-button-spinner]").forEach((node) => node.remove());
+    }
+}
+
+export class IncButtonGroupElement extends IncElement {
+    static get observedAttributes() {
+        return ["size", "label"];
+    }
+
+    connectedCallback() {
+        addClass(this, "inc-button-group");
+        this.sync();
+    }
+
+    attributeChangedCallback() {
+        if (this.isConnected) {
+            this.sync();
+        }
+    }
+
+    sync() {
+        addClass(this, "inc-button-group");
+        this.setAttribute("part", "button-group");
+        removeMatchingClasses(this, (token) => token.startsWith("inc-button-group--"));
+
+        const size = normalizeToken(this.getAttribute("size"));
+        if (BUTTON_SIZES.has(size)) {
+            this.classList.add(`inc-button-group--${size}`);
+        }
+
+        this.setAttribute("role", "group");
+        const label = this.getAttribute("label") || this.getAttribute("aria-label") || "";
+        if (label) {
+            this.setAttribute("aria-label", label);
+        } else {
+            this.removeAttribute("aria-label");
+        }
+    }
+}
+
+export class IncButtonToolbarElement extends IncElement {
+    static get observedAttributes() {
+        return ["label", "orientation"];
+    }
+
+    connectedCallback() {
+        addClass(this, "inc-button-toolbar");
+        this.sync();
+    }
+
+    attributeChangedCallback() {
+        if (this.isConnected) {
+            this.sync();
+        }
+    }
+
+    sync() {
+        addClass(this, "inc-button-toolbar");
+        this.setAttribute("part", "button-toolbar");
+        this.setAttribute("role", "toolbar");
+
+        const orientation = normalizeToken(this.getAttribute("orientation"));
+        if (orientation === "vertical") {
+            this.setAttribute("aria-orientation", "vertical");
+        } else {
+            this.removeAttribute("aria-orientation");
+        }
+
+        const label = this.getAttribute("label") || this.getAttribute("aria-label") || "";
+        if (label) {
+            this.setAttribute("aria-label", label);
+        } else {
+            this.removeAttribute("aria-label");
+        }
+    }
+}
+
+export class IncCloseButtonElement extends IncElement {
+    static get observedAttributes() {
+        return ["label", "variant"];
+    }
+
+    connectedCallback() {
+        addClass(this, "inc-close-button");
+        this.sync();
+    }
+
+    attributeChangedCallback() {
+        if (this.isConnected) {
+            this.sync();
+        }
+    }
+
+    sync() {
+        addClass(this, "inc-close-button");
+        this.setAttribute("part", "close-button");
+        const control = this.ensureControl();
+        const variant = normalizeToken(this.getAttribute("variant"));
+
+        control.className = "inc-close-button";
+        control.setAttribute("part", "control");
+        if (variant === "white") {
+            control.classList.add("inc-close-button--white");
+        }
+
+        control.type = "button";
+        control.setAttribute("aria-label", this.getAttribute("label") || "Close");
+        if (!control.childNodes.length) {
+            control.textContent = "×";
+        }
+    }
+
+    ensureControl() {
+        const existing = this._control || this.querySelector(":scope > button.inc-close-button");
+        if (existing) {
+            this._control = existing;
+            return existing;
+        }
+
+        const control = document.createElement("button");
+        const previous = this.querySelector(":scope > a.inc-close-button");
+        if (previous) {
+            moveChildNodes(previous, control);
+            previous.replaceWith(control);
+        } else {
+            moveChildNodes(this, control);
+            this.append(control);
+        }
+        this._control = control;
+        return control;
+    }
+}
+
+export class IncAlertElement extends IncElement {
+    static get observedAttributes() {
+        return ["tone", "variant", "dismissible", "dismiss-label"];
+    }
+
+    connectedCallback() {
+        addClass(this, "inc-alert");
+        this.bindEvents();
+        this.sync();
+    }
+
+    disconnectedCallback() {
+        if (this._boundClick) {
+            this.removeEventListener("click", this._boundClick);
+        }
+    }
+
+    attributeChangedCallback() {
+        if (this.isConnected) {
+            this.sync();
+        }
+    }
+
+    bindEvents() {
+        if (this._boundClick) {
+            return;
+        }
+
+        this._boundClick = (event) => {
+            const dismiss = event.target.closest("[data-inc-alert-dismiss]");
+            if (!dismiss || !this.contains(dismiss)) {
+                return;
+            }
+
+            event.preventDefault();
+            this.hide();
+        };
+
+        this.addEventListener("click", this._boundClick);
+    }
+
+    sync() {
+        addClass(this, "inc-alert");
+        this.setAttribute("part", "alert");
+        removeMatchingClasses(this, (token) => token.startsWith("inc-alert--"));
+
+        const tone = normalizeToken(this.getAttribute("tone") || this.getAttribute("variant")) || "info";
+        const resolvedTone = BADGE_TONES.has(tone) ? tone : "info";
+        this.classList.add(`inc-alert--${resolvedTone}`);
+
+        if (toBoolean(this.getAttribute("dismissible"))) {
+            this.classList.add("inc-alert--dismissible");
+            this.ensureDismissButton();
+        } else {
+            this.removeDismissButton();
+        }
+
+        if (!this.hasAttribute("role")) {
+            this.setAttribute("role", resolvedTone === "info" || resolvedTone === "secondary" ? "status" : "alert");
+        }
+        if (!this.hasAttribute("aria-live")) {
+            this.setAttribute("aria-live", this.getAttribute("role") === "alert" ? "assertive" : "polite");
+        }
+        this.setAttribute("aria-atomic", "true");
+    }
+
+    ensureDismissButton() {
+        let button = this.querySelector(":scope > [data-inc-alert-dismiss]");
+        if (!button) {
+            button = document.createElement("button");
+            button.type = "button";
+            button.dataset.incAlertDismiss = "true";
+            this.append(button);
+        }
+
+        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 = "×";
+        }
+        return button;
+    }
+
+    removeDismissButton() {
+        this.querySelectorAll(":scope > [data-inc-alert-dismiss]").forEach((node) => node.remove());
+    }
+
+    hide() {
+        this.hidden = true;
+        this.setAttribute("aria-hidden", "true");
+        this.emit("dismiss", { hidden: true });
+    }
+}
+
+export class IncEmptyStateElement extends IncElement {
+    connectedCallback() {
+        addClass(this, "inc-empty-state");
+        this.sync();
+    }
+
+    sync() {
+        addClass(this, "inc-empty-state");
+        this.setAttribute("part", "empty-state content icon body actions");
+
+        const content = ensureNode(this, ".inc-empty-state__content", () => {
+            const node = document.createElement("div");
+            node.className = "inc-empty-state__content";
+            node.innerHTML = [
+                '<div class="inc-empty-state__icon" part="icon"></div>',
+                '<div class="inc-empty-state__body" part="body"></div>',
+                '<div class="inc-empty-state__actions" part="actions"></div>',
+            ].join("");
+            return node;
+        });
+
+        const icon = ensureNode(content, ".inc-empty-state__icon", () => {
+            const node = document.createElement("div");
+            node.className = "inc-empty-state__icon";
+            node.setAttribute("part", "icon");
+            return node;
+        });
+        const body = ensureNode(content, ".inc-empty-state__body", () => {
+            const node = document.createElement("div");
+            node.className = "inc-empty-state__body";
+            node.setAttribute("part", "body");
+            return node;
+        });
+        const actions = ensureNode(content, ".inc-empty-state__actions", () => {
+            const node = document.createElement("div");
+            node.className = "inc-empty-state__actions";
+            node.setAttribute("part", "actions");
+            return node;
+        });
+
+        Array.from(this.childNodes).forEach((node) => {
+            if (node === content) {
+                return;
+            }
+
+            if (node.nodeType === Node.ELEMENT_NODE && node.getAttribute("slot") === "icon") {
+                node.removeAttribute("slot");
+                icon.append(node);
+                return;
+            }
+
+            if (node.nodeType === Node.ELEMENT_NODE && node.getAttribute("slot") === "actions") {
+                node.removeAttribute("slot");
+                actions.append(node);
+                return;
+            }
+
+            body.append(node);
+        });
+    }
+}
+
+const actionDefinitions = [
+    ["inc-button", IncButtonElement],
+    ["inc-button-group", IncButtonGroupElement],
+    ["inc-button-toolbar", IncButtonToolbarElement],
+    ["inc-close-button", IncCloseButtonElement],
+    ["inc-alert", IncAlertElement],
+    ["inc-empty-state", IncEmptyStateElement],
+];
+
+const actionComponents = {
+    IncButtonElement,
+    IncButtonGroupElement,
+    IncButtonToolbarElement,
+    IncCloseButtonElement,
+    IncAlertElement,
+    IncEmptyStateElement,
+};
+
+function defineActionComponents(registry = globalThis.customElements) {
+    if (!registry || typeof registry.define !== "function" || typeof registry.get !== "function") {
+        return [];
+    }
+
+    const defined = [];
+    for (const [tagName, ctor] of actionDefinitions) {
+        if (!registry.get(tagName)) {
+            registry.define(tagName, ctor);
+            defined.push(tagName);
+        }
+    }
+
+    return defined;
+}
+
+if (typeof module !== "undefined" && module.exports) {
+    module.exports = {
+        defineActionComponents,
+        actionDefinitions,
+        actionComponents,
+        IncButtonElement,
+        IncButtonGroupElement,
+        IncButtonToolbarElement,
+        IncCloseButtonElement,
+        IncAlertElement,
+        IncEmptyStateElement,
+    };
+}
+
+if (typeof globalThis !== "undefined") {
+    const namespace = globalThis.IncWebComponents || (globalThis.IncWebComponents = {});
+    namespace.actions = Object.assign({}, namespace.actions, {
+        defineActionComponents,
+        actionDefinitions,
+        components: actionComponents,
+    });
+}