@incursa/ui-kit 1.0.1 → 1.4.0

package/src/web-components/README.md

@@ -0,0 +1,92 @@
+# Web Components Runtime Notes
+
+This folder contains the additive browser-native layer for `@incursa/ui-kit`.
+
+The CSS-first [`inc-*`](../../reference.html) class surface remains the canonical API. The Web Component layer exists so the same design language can also be consumed from plain HTML, JavaScript, and browser-native primitives without creating a second design system.
+
+## Public Entry Point
+
+- Package entrypoint: `@incursa/ui-kit/web-components`
+- Style entrypoint: `@incursa/ui-kit/web-components/style.css`
+- 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`
+- 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.
+
+Recommended browser usage:
+
+```html
+<link rel="stylesheet" href="/node_modules/@incursa/ui-kit/web-components/style.css">
+<script type="module">
+    import "@incursa/ui-kit/web-components";
+</script>
+```
+
+The runtime auto-defines the shipped elements on load. If a consumer needs explicit registry control, `registerIncWebComponents()` remains available.
+
+## Runtime Rules
+
+- Keep the layer additive.
+- Reuse the current design tokens, CSS vocabulary, and helper behavior where they already exist.
+- Prefer light DOM and slotted native content by default.
+- Use open Shadow DOM only when a component needs a stable internal scaffold that materially improves correctness or maintainability.
+- Keep public tag names in the [`inc-`](../../reference.html) namespace and align them with the CSS family names whenever possible.
+- Expose public state through attributes and mirrored properties only when that state belongs in the contract.
+- Dispatch DOM events instead of framework callbacks.
+- Clean up observers, timers, and listeners on disconnect.
+
+## Current Source Layout
+
+- [`shared.js`](shared.js)
+  Shared parsing, reflection, event, and namespace helpers.
+- [`base-element.js`](base-element.js)
+  The `IncElement` base class, including reflected attribute/property wiring and slot helpers.
+- [`registry.js`](registry.js)
+  Idempotent registration helpers and the `IncWebComponents.registry` namespace.
+- [`controllers/focus.js`](controllers/focus.js)
+  Shared focus utilities for focus trapping, focus restoration, and focusable-element discovery.
+- [`controllers/selection.js`](controllers/selection.js)
+  Roving tabindex and keyboard navigation helpers for selection-based widgets.
+- [`controllers/overlay.js`](controllers/overlay.js)
+  Shared open/close, escape, backdrop, and focus-restoration behavior for overlays.
+- [`controllers/theme.js`](controllers/theme.js)
+  Shared root-theme helpers and the legacy bridge used by theme controls.
+- [`components/layout.js`](components/layout.js)
+  Layout and shell custom elements.
+- [`components/navigation.js`](components/navigation.js)
+  Navbar, tabs, and user-menu custom elements.
+- [`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.
+- [`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.
+
+As more families land, keep them in this same shape: small shared controllers plus family modules that register their public elements through the registry.
+
+## Design Intent
+
+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.
+- 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.
+
+## Maintenance Notes
+
+When you add or change a component:
+
+1. Reuse `IncElement` or the shared controllers before inventing new behavior.
+2. Keep the public contract declarative and observable in the DOM.
+3. Update the package docs and the browser examples together.
+4. Add or update Playwright coverage for keyboard, focus, dismissal, theming, and accessibility behavior.
+5. Do not introduce a second token family or styling vocabulary.
+
+The CSS class surface and the Web Component layer are meant to evolve together. If a change cannot be explained in terms of the existing [`inc-*`](../../reference.html) vocabulary, it is probably the wrong change.

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

@@ -0,0 +1,40 @@
+# Web Components Runtime Notes
+
+This folder ships the optional `./web-components` entrypoint for the UI kit.
+
+## v1 Scope
+
+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`
+- overlays: `inc-disclosure`, `inc-dialog`, `inc-drawer`
+
+## Contract shape
+
+- CSS-first is still canonical. Components reuse existing `inc-*` class contracts.
+- 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:
+  - `components/layout.js`
+  - `components/navigation.js`
+  - `components/forms.js`
+  - `components/feedback.js`
+  - `components/overlays.js`
+- Public registration API is idempotent:
+  - `window.IncWebComponents.defineAll()`
+  - `window.IncWebComponents.registerIncWebComponents()`
+- The dedicated entrypoint auto-defines components on load.
+
+## Explicitly deferred surfaces in v1
+
+- tooltip and popover components
+- permission-banner and toast runtime orchestration
+- table/data wrappers and grid-like behavior
+- filter/file/bulk workflow wrappers
+- legacy helper-managed modal/offcanvas compatibility wrappers
+
+Those surfaces remain CSS-first until a follow-up requirement pass promotes them.

package/src/web-components/base-element.js

@@ -0,0 +1,193 @@
+import {
+    dispatchComponentEvent,
+    getAssignedSlotElements,
+    normalizeAttributeConfig,
+    parseValueFromAttribute,
+    readReflectedAttribute,
+    reflectAttributeValue,
+    serializeValueForAttribute,
+} from "./shared.js";
+
+const HostElement = typeof HTMLElement === "undefined" ? class {} : HTMLElement;
+const metadataByConstructor = new WeakMap();
+
+function buildMetadata(constructor) {
+    if (metadataByConstructor.has(constructor)) {
+        return metadataByConstructor.get(constructor);
+    }
+
+    const reflectedConfig = constructor.reflectedAttributes || {};
+    const propertyToConfig = new Map();
+    const attributeToConfig = new Map();
+
+    Object.keys(reflectedConfig).forEach((property) => {
+        const normalized = normalizeAttributeConfig(property, reflectedConfig[property]);
+        propertyToConfig.set(property, normalized);
+        attributeToConfig.set(normalized.attribute, normalized);
+
+        if (Object.prototype.hasOwnProperty.call(constructor.prototype, property)) {
+            return;
+        }
+
+        Object.defineProperty(constructor.prototype, property, {
+            configurable: true,
+            enumerable: true,
+            get() {
+                return this._propertyValues.get(property);
+            },
+            set(value) {
+                this._setReflectedPropertyValue(property, value, { reflect: true });
+            },
+        });
+    });
+
+    const metadata = {
+        propertyToConfig,
+        attributeToConfig,
+    };
+
+    metadataByConstructor.set(constructor, metadata);
+    return metadata;
+}
+
+class IncElement extends HostElement {
+    static reflectedAttributes = {};
+
+    static get observedAttributes() {
+        const metadata = buildMetadata(this);
+        return [...metadata.attributeToConfig.keys()];
+    }
+
+    constructor() {
+        super();
+        this._propertyValues = new Map();
+        this._slotListeners = new Map();
+        this._isReflectingAttribute = false;
+        this._isConnected = false;
+
+        const metadata = buildMetadata(this.constructor);
+
+        metadata.propertyToConfig.forEach((config, property) => {
+            if (this.hasAttribute(config.attribute)) {
+                this._propertyValues.set(property, readReflectedAttribute(this, config));
+                return;
+            }
+
+            this._propertyValues.set(property, config.defaultValue);
+        });
+    }
+
+    connectedCallback() {
+        this._isConnected = true;
+        if (typeof this.onConnected === "function") {
+            this.onConnected();
+        }
+    }
+
+    disconnectedCallback() {
+        this._isConnected = false;
+        this._slotListeners.forEach((listener, slot) => {
+            slot.removeEventListener("slotchange", listener);
+        });
+        this._slotListeners.clear();
+
+        if (typeof this.onDisconnected === "function") {
+            this.onDisconnected();
+        }
+    }
+
+    attributeChangedCallback(name, oldValue, newValue) {
+        if (oldValue === newValue) {
+            return;
+        }
+
+        const metadata = buildMetadata(this.constructor);
+        const config = metadata.attributeToConfig.get(name);
+
+        if (config) {
+            const parsed = parseValueFromAttribute(newValue, config);
+            this._setReflectedPropertyValue(config.property, parsed, { reflect: false });
+        }
+
+        if (typeof this.onAttributeValueChanged === "function") {
+            this.onAttributeValueChanged(name, oldValue, newValue);
+        }
+    }
+
+    emit(type, detail = {}, options = {}) {
+        return dispatchComponentEvent(this, type, detail, options);
+    }
+
+    getSlotElements(slotName = "") {
+        return getAssignedSlotElements(this, slotName);
+    }
+
+    observeSlot(slotName = "", callback = null) {
+        const selector = slotName ? `slot[name="${slotName}"]` : "slot:not([name])";
+        const slot = this.querySelector(selector);
+
+        if (typeof HTMLSlotElement === "undefined" || !(slot instanceof HTMLSlotElement)) {
+            return () => {};
+        }
+
+        const listener = () => {
+            if (typeof callback === "function") {
+                callback(this.getSlotElements(slotName));
+            }
+        };
+
+        slot.addEventListener("slotchange", listener);
+        this._slotListeners.set(slot, listener);
+        listener();
+
+        return () => {
+            slot.removeEventListener("slotchange", listener);
+            this._slotListeners.delete(slot);
+        };
+    }
+
+    reflectAllProperties() {
+        const metadata = buildMetadata(this.constructor);
+        metadata.propertyToConfig.forEach((config, property) => {
+            const value = this._propertyValues.get(property);
+            if (!config.reflect) {
+                return;
+            }
+
+            const serialized = serializeValueForAttribute(value, config);
+            reflectAttributeValue(this, config.attribute, serialized);
+        });
+    }
+
+    _setReflectedPropertyValue(property, value, options = {}) {
+        const metadata = buildMetadata(this.constructor);
+        const config = metadata.propertyToConfig.get(property);
+
+        if (!config) {
+            this._propertyValues.set(property, value);
+            return;
+        }
+
+        const previousValue = this._propertyValues.get(property);
+        if (Object.is(previousValue, value)) {
+            return;
+        }
+
+        this._propertyValues.set(property, value);
+
+        if (options.reflect !== false && config.reflect && !this._isReflectingAttribute) {
+            const serialized = serializeValueForAttribute(value, config);
+            this._isReflectingAttribute = true;
+            reflectAttributeValue(this, config.attribute, serialized);
+            this._isReflectingAttribute = false;
+        }
+
+        if (typeof this.onPropertyValueChanged === "function") {
+            this.onPropertyValueChanged(property, previousValue, value);
+        }
+    }
+}
+
+export {
+    IncElement,
+};