@ibgib/web-gib 0.0.46 → 0.0.48

package/src/ui/component/ARCHITECTURE.md

@@ -0,0 +1,180 @@
+# IbGib Dynamic UI Component Architecture
+
+This document describes the design of the `@ibgib` UI microframework in `web-gib` and details the base classes, routing service, proxy-backed model synchronization, and form handling base class.
+
+---
+
+## 📖 Component System Architecture Summary
+
+*   **Overall Approach**: A timeline-driven UI microframework built on standard HTML5 Web Components (Shadow DOM). Rather than relying on standard local state stores, UI rendering, routing, and lifecycle transitions are powered by the native ibgib protocol and Merkle-DAG content-addressing timelines.
+*   **Registry & Routing**: `IbGibComponentService` acts as a central registry. When navigating, the service filters registered `IbGibDynamicComponentMeta` factories by path and regex, executing `fnHandleRoute()` to select and inject the matching component instance.
+*   **Backing Model Sync via Proxy**:
+    *   Components maintain a live binding to their backing data via a **`LiveProxyIbGib`**.
+    *   When the local space or metaspace registers a new mutation/frame on the timeline, the proxy fires `contextUpdated$` and `newContextChild$` (if it's a parent ibgib with children that were rel8d/unrel8d).
+    *   The base class subscribes to these streams, automatically updating `this.ibGibAddr` and invoking `renderUI()` to redraw the component.
+
+---
+
+## 🏛️ Core Classes Reference
+
+### 1. `IbGibComponentService`
+A singleton service (`componentSvc`) that acts as a central registry and router for all shell components.
+*   **Registration**: Components register their factory metadata blueprints using `registerComponentMeta(meta)`.
+*   **Resolution**: When routing, `getComponentInstance()` iterates through registered components, first testing `routeRegExp` and then calling `fnHandleRoute()` for fine-grained content validation.
+*   **Injection**: `inject(parentEl, instance)` handles clearing old views, appending the new custom element, and handling injection errors.
+
+### 2. `IbGibDynamicComponentMetaBase`
+The abstract factory blueprint class representing a component type's metadata and routing constraints.
+*   **Properties**:
+    *   `componentName`: The custom HTML tag name (e.g. `keystone-creator`).
+    *   `routeRegExp`: Prefilter regex matching current route path.
+    *   `fnHandleRoute`: Detailed route matching lambda.
+    *   `bootstrapPromise`: Deferment promise coordinating with the global ibgib bootstrap state.
+*   **Methods**:
+    *   `createInstance({ path, ibGibAddr })`: Creates the concrete `HTMLElement` instance.
+
+### 3. `IbGibDynamicComponentInstanceBase`
+The base `HTMLElement` custom element class that coordinates DOM lifecycles and `ibgib` context bindings.
+*   **Backing Proxy & Subscription**:
+    *   `loadIbGib()`: Pulls the initial backing data record from the space, wrapping it in a `LiveProxyIbGib`.
+    *   `handleContextUpdated()`: Reacts to `contextUpdated$` events, synchronizing `this.ibGibAddr`.
+    *   `handleNewContextChild()`: Reacts to child timeline changes (e.g., additions or removals of related nodes).
+*   **Local Coupling**:
+    *   `initSettings()`: Manages local-only configurations (like active identities or layout preferences) coupled to a shared timeline using mapping indices without mutating the domain data.
+*   **Lifecycle Hooks**:
+    *   `connectedCallback()`: Attaches the Shadow DOM template, style arrays, and triggers `created()`.
+    *   `created()`: Abstract hook called after the DOM is ready for component-specific setup and render.
+    *   `renderUI()`: Triggers UI redrawing, resolving unique color palettes (`getDeterministicColorInfo`) based on the backing `ibgib`'s hash.
+    *   `disconnectedCallback()` / `disconnected()`: Handles event listener unbinding and proxy resource cleanup when removed from the DOM.
+
+### 4. `IbGibFormInstanceBase`
+The intermediate abstract base class specifically designed to handle interactive form operations, loading states, and validation rules.
+*   **Subclass Responsibility**: Inherited by components containing inputs and action buttons (e.g., `KeystoneCreatorComponentInstance`).
+*   **Standard Methods**:
+    *   `setLoading(loading, selector)`: Automatically toggles submit/generate button disabled state and updates text.
+    *   `setStatus(msg, type, areaId, textId)`: Manages error/success status elements and toggles the `hidden` class.
+    *   `validateForm(formSelector)`: Inspects all form controls within the shadow root and runs HTML5 Constraint Validation checks.
+    *   `validateInputPattern(opts)`: Validates a single input/textarea element's value against a custom RegExp pattern, adding/removing the `invalid` CSS class and updating validity messages.
+    *   `dispatchShellMessage(message, level)`: Dispatches bubbling, composed Custom Events (`ibgib-ui-message`) to notify the parent Shell.
+
+---
+
+## 📋 Implementation Plan: `IbGibFormInstanceBase`
+
+```mermaid
+graph TD
+    HTMLElement --> IbGibDynamicComponentInstanceBase
+    IbGibDynamicComponentInstanceBase --> IbGibFormInstanceBase
+    IbGibFormInstanceBase --> KeystoneCreatorComponentInstance
+```
+
+### 1. Class Interface Implementation
+Introduce `IbGibFormInstanceBase` inside `libs/web-gib/src/ui/component/ibgib-dynamic-component-bases.mts`:
+
+```typescript
+export abstract class IbGibFormInstanceBase<TIbGib extends IbGib_V1 = IbGib_V1, TElements = any>
+    extends IbGibDynamicComponentInstanceBase<TIbGib, TElements> {
+
+    protected setLoading(loading: boolean, submitBtnSelector = '#btn-submit, #btn-generate'): void {
+        if (!this.shadowRoot) return;
+        const btn = this.shadowRoot.querySelector(submitBtnSelector) as HTMLButtonElement | null;
+        if (btn) {
+            btn.disabled = loading;
+            // Optionally toggle an attribute or standard class
+            if (loading) {
+                btn.setAttribute('data-loading', 'true');
+            } else {
+                btn.removeAttribute('data-loading');
+            }
+        }
+    }
+
+    protected setStatus(
+        msg: string,
+        type: 'info' | 'success' | 'error',
+        statusAreaId = 'status-area',
+        statusTextId = 'status-text'
+    ): void {
+        if (!this.shadowRoot) return;
+        const area = this.shadowRoot.getElementById(statusAreaId);
+        const text = this.shadowRoot.getElementById(statusTextId);
+
+        if (text) {
+            text.textContent = msg;
+            text.className = `status-msg ${type}`;
+        }
+        if (area) {
+            if (msg) {
+                area.classList.remove('hidden');
+            } else {
+                area.classList.add('hidden');
+            }
+        }
+    }
+
+    protected dispatchShellMessage(message: string, level: 'info' | 'success' | 'warning' | 'error'): void {
+        this.dispatchEvent(new CustomEvent(EVENT_IBGIB_UI_MESSAGE, {
+            detail: { message, level, source: this.tagName.toLowerCase() },
+            bubbles: true,
+            composed: true
+        }));
+    }
+
+    protected validateForm(formSelector = 'form'): boolean {
+        if (!this.shadowRoot) return true;
+        const form = this.shadowRoot.querySelector(formSelector) as HTMLFormElement | null;
+        if (form) {
+            return form.checkValidity();
+        }
+
+        // Fallback: check all individual inputs in shadowRoot
+        const inputs = this.shadowRoot.querySelectorAll('input, select, textarea');
+        let isValid = true;
+        for (const input of Array.from(inputs)) {
+            const el = input as HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement;
+            if (!el.checkValidity()) {
+                isValid = false;
+                el.reportValidity();
+                break; // Stop on first invalid field
+            }
+        }
+        return isValid;
+    }
+
+    protected validateInputPattern({
+        input,
+        pattern,
+        errorMessage,
+        required = true,
+    }: {
+        input: HTMLInputElement | HTMLTextAreaElement | null;
+        pattern: RegExp;
+        errorMessage: string;
+        required?: boolean;
+    }): boolean {
+        if (!input) return true;
+        const val = input.value.trim();
+
+        if (!val && !required) {
+            input.classList.remove('invalid');
+            input.setCustomValidity('');
+            return true;
+        }
+
+        const isValid = pattern.test(val);
+        if (!isValid) {
+            input.classList.add('invalid');
+            input.setCustomValidity(errorMessage);
+            input.reportValidity();
+        } else {
+            input.classList.remove('invalid');
+            input.setCustomValidity('');
+        }
+        return isValid;
+    }
+}
+```
+
+### 2. Integration
+*   Refactor `KeystoneCreatorComponentInstance` in `space-gib` to extend `IbGibFormInstanceBase` instead of `IbGibDynamicComponentInstanceBase`.
+*   Replace its local duplicate validation and loading methods with inherited calls.

package/src/ui/component/README.md

@@ -0,0 +1,201 @@
+# Custom @ibgib UI Component Framework
+
+This directory houses the custom `@ibgib` UI microframework. Rather than using conventional state-binding engines, this system leverages the native ibgib protocol and its Merkle-DAG content-addressing structure to orchestrate a unique, timeline-driven reactivity. Component instances are implemented as native HTML5 Web Components (Shadow DOM) and bind directly to evolutionary `ibGib` timelines, resolving, mutating, and updating state in sync with the DLT storage.
+
+For the internal architectural details and class reference, see [ARCHITECTURE.md](file:///c:/Users/billm/antigravity/ibgib/libs/web-gib/src/ui/component/ARCHITECTURE.md).
+
+For a helper agentic skill, see the [ibgib-create-component folder](file:///c:\Users\billm\antigravity\ibgib\.agents\skills\ibgib-create-component)
+
+---
+
+## 💡 Overview
+
+Unlike standard frameworks (React, Vue, etc.) that bind to a local central store, `@ibgib` components are linked to a backing `ibgib` timeline.
+- The component uses the timeline's genesis address (its immutable `tjpGib`) as its identifier.
+- The component subscribes to the metaspace's local pubsub/event bus.
+- When mutations or new frames occur on the timeline, the component automatically evolves, synchronizes its state, and redraws itself.
+
+The protocol itself is a universe-sized address spacetime that allows truly distributed data to drive the reactivity.
+
+### The Component Framework Parts
+
+1. **`IbGibComponentService` (Registry & Router)**: A central registry and router singleton. When navigating, it matches route pathing, selects the appropriate component factory meta, and injects the instantiated element into the target DOM.
+2. **`IbGibDynamicComponentMetaBase` (Factory Meta)**: A metadata blueprint specifying the component's HTML tag name, routing regex, and containing the `createInstance` factory method.
+3. **`IbGibDynamicComponentInstanceBase` (UI Component)**: The concrete custom element inheriting from `HTMLElement` (i.e. web component). It wraps the backing data in a `LiveProxyIbGib` and automatically triggers lifecycle/render hooks on timeline updates.
+4. **`IbGibFormInstanceBase` (Form Handler)**: An intermediate base class extending the instance base, adding status reporting, button load toggling, and validation for behavior specific to forms.
+
+---
+
+## 🛠️ How to Create an IbGib UI Component
+
+### 1. Registering your Component Metadata
+To register your component with the shell router, extend `IbGibDynamicComponentMetaBase` and call `componentSvc.registerComponentMeta(new MyComponentMeta())` during your application bootstrap:
+
+```typescript
+import { IbGibDynamicComponentMetaBase } from '@ibgib/web-gib/dist/ui/component/ibgib-dynamic-component-bases.mjs';
+import { componentSvc } from '@ibgib/web-gib/dist/ui/component/component-service.mjs';
+
+export const MY_COMPONENT_NAME = 'my-custom-component';
+
+export class MyComponentMeta extends IbGibDynamicComponentMetaBase {
+    routeRegExp = new RegExp(`^${MY_COMPONENT_NAME}$`);
+    componentName = MY_COMPONENT_NAME;
+
+    createInstance(opts) {
+        return document.createElement(this.componentName);
+    }
+}
+
+// Register with central service
+componentSvc.registerComponentMeta(new MyComponentMeta());
+```
+
+### 2. Implementing the Component Instance
+Your component class extends `IbGibDynamicComponentInstanceBase`. You override `created()` for DOM initialization and `renderUI()` for drawing data:
+
+```typescript
+import { IbGibDynamicComponentInstanceBase } from '@ibgib/web-gib/dist/ui/component/ibgib-dynamic-component-bases.mjs';
+import thisHtml from './my-component.html';
+import thisCss from './my-component.css';
+
+export class MyComponentInstance extends IbGibDynamicComponentInstanceBase {
+    protected lc = '[MyComponentInstance]';
+
+    // Specify the HTML template and stylesheets
+    protected get html() { return thisHtml; }
+    protected get css() { return [thisCss]; }
+
+    /** Called once when custom element is connected to the DOM */
+    override async created(): Promise<void> {
+        // Query elements within this.shadowRoot
+        this.elements.myValueEl = this.shadowRoot.getElementById('value-display');
+
+        // Load backing model if ibGibAddr was passed
+        if (this.ibGibAddr && !this.ibGib) {
+            await this.loadIbGib();
+        }
+        await this.renderUI();
+    }
+
+    /** Called initially, and automatically on backing ibgib updates */
+    override async renderUI(): Promise<void> {
+        if (!this.ibGib) return;
+
+        // Dynamically update elements
+        this.elements.myValueEl.textContent = this.ibGib.data?.value ?? '';
+    }
+}
+
+customElements.define(MY_COMPONENT_NAME, MyComponentInstance);
+```
+
+---
+
+## 📝 Form Handling & Validation UI
+
+When building forms, your component instance should extend **`IbGibFormInstanceBase`** instead of `IbGibDynamicComponentInstanceBase`. This adds powerful built-in validation and status tracking.
+
+### Form Validation API Reference
+
+*   **`validateForm(formSelector?: string): boolean`**
+    Checks standard HTML5 constraint validation on all inputs in the form (or shadow root). Reports validity and returns `true` if valid, `false` otherwise.
+*   **`validateInputPattern(opts: ValidateInputPatternOpts): boolean`**
+    Validates a single input's value against a JS `RegExp`. If invalid, it adds the `.invalid` CSS class to the input element, sets custom error validity messages, and calls `reportValidity()` to trigger standard browser tooltip notifications.
+*   **`setLoading(loading: boolean, submitBtnSelector?: string): void`**
+    Toggles the `disabled` state on the submit/action button, adding a `data-loading` attribute.
+*   **`setStatus(msg: string, type: 'info' | 'success' | 'error', statusAreaId?: string, statusTextId?: string): void`**
+    Displays success/error banners on the form page, removing the `.hidden` class from the status area wrapper.
+
+### Validation Example Flow
+
+Here is how to structure form validation and clear state flags as the user types:
+
+#### HTML Template (`my-form.html`)
+```html
+<div id="container">
+    <div id="status-area" class="hidden">
+        <p id="status-text"></p>
+    </div>
+
+    <form id="my-form">
+        <label for="input-username">Username</label>
+        <input type="text" id="input-username" required />
+
+        <button type="submit" id="btn-submit">Submit</button>
+    </form>
+</div>
+```
+
+#### CSS Stylesheet (`my-form.css`)
+```css
+/* Styling input fields marked as invalid */
+input.invalid {
+    border: 2px solid var(--clr-danger, #ff4444);
+    box-shadow: 0 0 5px rgba(255, 68, 68, 0.5);
+    outline: none;
+}
+
+.status-msg.error {
+    color: var(--clr-danger, #ff4444);
+    font-weight: 500;
+}
+.status-msg.success {
+    color: var(--clr-success, #00c851);
+}
+```
+
+#### TypeScript Implementation (`my-form.mts`)
+```typescript
+import { IbGibFormInstanceBase } from '@ibgib/web-gib/dist/ui/component/ibgib-dynamic-component-bases.mjs';
+import { KEYSTONE_USERNAME_REGEXP } from '@ibgib/core-gib/dist/keystone/keystone-constants.mjs';
+
+export class MyFormInstance extends IbGibFormInstanceBase {
+
+    override async created(): Promise<void> {
+        this.elements.inputUsername = this.shadowRoot.getElementById('input-username');
+        this.elements.btnSubmit = this.shadowRoot.getElementById('btn-submit');
+
+        this.initHandlers();
+    }
+
+    private initHandlers() {
+        this.shadowRoot.getElementById('my-form').addEventListener('submit', (e) => {
+            e.preventDefault();
+            this.handleSubmit();
+        });
+
+        // CRITICAL: Clear the invalid CSS class as the user starts typing
+        this.elements.inputUsername.addEventListener('input', () => {
+            this.elements.inputUsername.classList.remove('invalid');
+        });
+    }
+
+    private async handleSubmit() {
+        // 1. Perform custom Regexp validation
+        const isValidUsername = this.validateInputPattern({
+            input: this.elements.inputUsername,
+            pattern: KEYSTONE_USERNAME_REGEXP,
+            errorMessage: "Username must be 1-63 characters (alphanumeric, dots, hyphens, underscores).",
+            required: true
+        });
+
+        if (!isValidUsername) {
+            this.setStatus("Please correct the invalid fields.", "error");
+            return;
+        }
+
+        // 2. Toggle Loading State
+        this.setLoading(true, '#btn-submit');
+        this.setStatus("Submitting username...", "info");
+
+        try {
+            // ... perform business logic / space evolution ...
+            this.setStatus("Form successfully submitted!", "success");
+        } catch (err) {
+            this.setStatus(`Error occurred: ${err.message}`, "error");
+        } finally {
+            this.setLoading(false, '#btn-submit');
+        }
+    }
+}
+```

package/src/ui/component/ibgib-dynamic-component-bases.mts

@@ -51,6 +51,7 @@ import { getAgentForDomainIbGib } from "../../witness/agent/agent-helpers.mjs";
 import { createSettings, getSectionName, getSettingsScope, getSettingsSection } from "../../common/settings/settings-helpers.mjs";
 import { IbGibSettings, SettingsIbGib_V1, SettingsWithTabs } from "../../common/settings/settings-types.mjs";
 import { SettingsType } from "../../common/settings/settings-constants.mjs";
+import { EVENT_IBGIB_UI_BUSY, EVENT_IBGIB_UI_MESSAGE } from "../ui-constants.mjs";
 
 const logalot = GLOBAL_LOG_A_LOT;
 
@@ -200,10 +201,51 @@ export abstract class IbGibDynamicComponentInstanceBase<TIbGib extends IbGib_V1
      */
     protected connectedCount = 0;
 
+    protected _isBusy: boolean = false;
     /**
-     * override this as needed
+     * Indicates whether the component is currently performing an asynchronous operation.
      */
-    public get isBusy(): boolean { return false; }
+    public get isBusy(): boolean { return this._isBusy; }
+
+    /**
+     * Updates the component's busy state, disabling elements and triggering events.
+     * Dispatches `EVENT_IBGIB_UI_BUSY` locally on the component and globally on the window.
+     */
+    protected showBusy({
+        isBusy,
+        title,
+        msg,
+        localOnly,
+        animationEmoji,
+    }: {
+        isBusy: boolean;
+        title?: string;
+        msg?: string;
+        localOnly?: boolean;
+        animationEmoji?: string;
+    }): void {
+        const lc = `${this.lc}[${this.showBusy.name}]`;
+        try {
+            this._isBusy = isBusy;
+
+            if (localOnly) {
+                // Dispatch locally on 'this' (bubbles so parent components can listen)
+                this.dispatchEvent(new CustomEvent(EVENT_IBGIB_UI_BUSY, {
+                    detail: { isBusy, title, msg, animationEmoji },
+                    bubbles: true,
+                    composed: true
+                }));
+            } else {
+                // Unless localOnly, dispatch directly on window (so shell receives it even if unmounted)
+                window.dispatchEvent(new CustomEvent(EVENT_IBGIB_UI_BUSY, {
+                    detail: { isBusy, title, msg, animationEmoji }
+                }));
+            }
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        }
+    }
 
     protected async getMetaspace(): Promise<MetaspaceService> {
         const lc = `${this.lc}[${this.getMetaspace.name}]`;
@@ -1369,3 +1411,184 @@ export abstract class IbGibDynamicComponentInstanceBase_ParentOfTabs<TSettings e
         }
     }
 }
+
+/**
+ * Intermediate abstract base class designed for dynamic interactive form elements.
+ * Provides standard wrappers for constraint validation, busy states, status reporting,
+ * and boundary-crossing shell notification events.
+ */
+export abstract class IbGibFormInstanceBase<TIbGib extends IbGib_V1 = IbGib_V1, TElements = any>
+    extends IbGibDynamicComponentInstanceBase<TIbGib, TElements> {
+
+    /**
+     * Updates the form's submit/generate button visual loading state.
+     * Disables the button, sets custom loading text, and marks it with data attributes
+     * during loading; restores the original text and removes attributes when complete.
+     */
+    protected setLoading(
+        loading: boolean,
+        submitBtnSelector = '#btn-submit, #btn-generate',
+        loadingText?: string
+    ): void {
+        if (!this.shadowRoot) return;
+        const btn = this.shadowRoot.querySelector(submitBtnSelector) as HTMLButtonElement | null;
+        if (btn) {
+            btn.disabled = loading;
+            if (loading) {
+                btn.setAttribute('data-loading', 'true');
+                if (loadingText) {
+                    btn.setAttribute('data-original-text', btn.textContent || '');
+                    btn.textContent = loadingText;
+                }
+            } else {
+                btn.removeAttribute('data-loading');
+                const orig = btn.getAttribute('data-original-text');
+                if (orig !== null) {
+                    btn.textContent = orig;
+                    btn.removeAttribute('data-original-text');
+                }
+            }
+        }
+    }
+
+    protected setStatus(
+        msg: string,
+        type: 'info' | 'success' | 'error',
+        statusAreaId = 'status-area',
+        statusTextId = 'status-text'
+    ): void {
+        if (!this.shadowRoot) return;
+        const area = this.shadowRoot.getElementById(statusAreaId);
+        const text = this.shadowRoot.getElementById(statusTextId);
+
+        if (text) {
+            text.textContent = msg;
+            text.className = `status-msg ${type}`;
+        }
+        if (area) {
+            if (msg) {
+                area.classList.remove('hidden');
+            } else {
+                area.classList.add('hidden');
+            }
+        }
+    }
+
+    protected dispatchShellMessage(message: string, level: 'info' | 'success' | 'warning' | 'error'): void {
+        this.dispatchEvent(new CustomEvent(EVENT_IBGIB_UI_MESSAGE, {
+            detail: { message, level, source: this.tagName.toLowerCase() },
+            bubbles: true,
+            composed: true
+        }));
+    }
+
+    protected validateForm(formSelector = 'form'): boolean {
+        if (!this.shadowRoot) return true;
+        const form = this.shadowRoot.querySelector(formSelector) as HTMLFormElement | null;
+        if (form) {
+            return form.checkValidity();
+        }
+
+        // Fallback: check all individual inputs in shadowRoot
+        const inputs = this.shadowRoot.querySelectorAll('input, select, textarea');
+        let isValid = true;
+        for (const input of Array.from(inputs)) {
+            const el = input as HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement;
+            if (!el.checkValidity()) {
+                isValid = false;
+                el.reportValidity();
+                break; // Stop on first invalid field
+            }
+        }
+        return isValid;
+    }
+
+    /**
+     * Validates a given input element's value against a RegExp pattern.
+     * Marks the input element with the 'invalid' class and sets a custom validity message if invalid.
+     */
+    protected validateInputPattern({
+        input,
+        pattern,
+        errorMessage,
+        required = true,
+    }: {
+        input: HTMLInputElement | HTMLTextAreaElement | null;
+        pattern: RegExp;
+        errorMessage: string;
+        required?: boolean;
+    }): boolean {
+        if (!input) return true;
+        const val = input.value.trim();
+
+        // If empty and not required, it is valid
+        if (!val && !required) {
+            input.classList.remove('invalid');
+            input.setCustomValidity('');
+            return true;
+        }
+
+        const isValid = pattern.test(val);
+        if (!isValid) {
+            input.classList.add('invalid');
+            input.setCustomValidity(errorMessage);
+            input.reportValidity();
+        } else {
+            input.classList.remove('invalid');
+            input.setCustomValidity('');
+        }
+        return isValid;
+    }
+
+    /**
+     * Overrides base component showBusy to handle form-specific side-effects
+     * (e.g. disabling form inputs, setting submit button loading state)
+     * before delegating to the base class event dispatchers.
+     */
+    protected override showBusy({
+        isBusy,
+        title,
+        msg,
+        localOnly,
+        submitBtnSelector,
+        loadingText,
+        animationEmoji,
+    }: {
+        isBusy: boolean;
+        title?: string;
+        msg?: string;
+        localOnly?: boolean;
+        submitBtnSelector?: string;
+        loadingText?: string;
+        animationEmoji?: string;
+    }): void {
+        const lc = `${this.lc}[${this.showBusy.name}]`;
+        try {
+            // Apply local form-specific side effects
+            this.setLoading(isBusy, submitBtnSelector, loadingText);
+            this.toggleAllInputsDisabled(isBusy);
+
+            // Delegate core state update and local/global event dispatching to base class
+            super.showBusy({
+                isBusy,
+                title,
+                msg,
+                localOnly,
+                animationEmoji
+            });
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        }
+    }
+
+    private toggleAllInputsDisabled(disabled: boolean): void {
+        if (!this.shadowRoot) { return; }
+        const inputs = this.shadowRoot.querySelectorAll('input, select, textarea, button');
+        inputs.forEach(input => {
+            // Don't disable the submit/generate button since setLoading handles its text/state
+            if (input.id === 'btn-submit' || input.id === 'btn-generate') { return; }
+            (input as HTMLInputElement | HTMLButtonElement).disabled = disabled;
+        });
+    }
+}

package/src/ui/ui-constants.mts

@@ -99,3 +99,13 @@ export const VALID_CSS_VARIABLES = [
  * going to use this for storing/restoring themes
  */
 export const UI_THEME_INFO_KEY = 'ui-theme-info';
+
+// #region Custom Events
+export const EVENT_IBGIB_SHELL_READY = 'ibgib-shell-ready';
+export const EVENT_IBGIB_UI_BUSY = 'ibgib-ui-busy';
+export const EVENT_IBGIB_UI_MESSAGE = 'ibgib-ui-message';
+export const EVENT_IBGIB_IDENTITY_REQUEST_CHANGE = 'ibgib-identity-request-change';
+export const EVENT_IBGIB_IDENTITY_CHANGED = 'ibgib-identity-changed';
+// #endregion Custom Events
+
+