@ibgib/web-gib 0.0.1

package/src/storage/storage-types.web.mts

@@ -0,0 +1,29 @@
+/**
+ * used to mimic the fs.Dirent interface.
+ * @see https://nodejs.org/api/fs.html#fs_class_fs_dirent
+ */
+export interface Dirent {
+    name: string;
+    isDirectory(): boolean;
+    isFile(): boolean;
+    /**
+     * Always false for IndexedDB
+     */
+    isBlockDevice(): boolean;
+    /**
+     * Always false for IndexedDB
+     */
+    isCharacterDevice(): boolean;
+    /**
+     * Always false for IndexedDB
+     */
+    isSymbolicLink(): boolean;
+    /**
+     * Always false for IndexedDB
+     */
+    isFIFO(): boolean;
+    /**
+     * Always false for IndexedDB
+     */
+    isSocket(): boolean;
+}

package/src/types.web.mts

@@ -0,0 +1,42 @@
+import { Gib } from "@ibgib/ts-gib/dist/types.mjs";
+import { GibInfo } from "@ibgib/ts-gib/dist/V1/types.mjs";
+
+/**
+ * deterministically driven colors based on a given {@link gib}
+ */
+export interface GibColorInfo {
+    /**
+     * Gib that was used to drive the color calculation
+     */
+    gib: Gib;
+    gibInfo: GibInfo;
+    /**
+     * Color that corresponds to the punctiliar part of {@link gib}
+     */
+    punctiliarColor: string;
+    /**
+     * Translucent version of {@link punctiliarColor}
+     */
+    punctiliarColorTranslucent: string;
+    /**
+     * contrasting color against punctiliar color
+     */
+    punctiliarColorContrast: string;
+    /**
+     * Color that corresponds to the tjp (timeline) part of {@link gib}
+     */
+    tjpColor?: string;
+    /**
+     * Translucent version of {@link tjpColor}
+     */
+    tjpColorTranslucent?: string;
+    /**
+     * contrasting color against tjp color
+     */
+    tjpColorContrast?: string;
+    /**
+     * If there was an error deriving the color info, this will show the error
+     * message.
+     */
+    errorMsg?: string;
+}

package/src/ui/component/component-types.mts

@@ -0,0 +1,241 @@
+import { ROOT_ADDR } from "@ibgib/ts-gib/dist/V1/constants.mjs";
+import { Gib, Ib, IbGibAddr } from "@ibgib/ts-gib/dist/types.mjs";
+import { IbGib_V1 } from "@ibgib/ts-gib/dist/V1/types.mjs";
+import { MetaspaceService } from "@ibgib/core-gib/dist/witness/space/metaspace/metaspace-types.mjs";
+
+import { AgentWitnessAny } from "../../witness/agent/agent-one-file.mjs";
+import { LiveProxyIbGib } from "../../witness/live-proxy-ibgib/live-proxy-ibgib-one-file.mjs";
+
+/**
+ * @see {@link IbGibDynamicComponentMeta.fnHandleRoute}
+ */
+export type FnHandleRouteType =
+    (arg: { path: string; ibGibAddr?: IbGibAddr | undefined; }) => Promise<boolean>;
+
+export interface IbGibDynamicComponentMetaCtorOpts {
+    /**
+     * @see {@link IbGibDynamicComponentMeta.fnGetMetaspace}
+     */
+    fnGetMetaspace: () => Promise<MetaspaceService>;
+    /**
+     * @see {@link IbGibDynamicComponentMeta.bootstrapPromise}
+     */
+    bootstrapPromise: Promise<void>;
+}
+
+/**
+ * This meta object is what registers with the component service. It decides
+ * if a component matches a given route, and if so, this contains the factory
+ * function to create the ibgib component instance (which will be the actual web
+ * component).
+ *
+ * So this is like a factory class, but contains more so it's lumped in as
+ * "meta".
+ *
+ * @see {@link IbGibDynamicComponentInstance}
+ */
+export interface IbGibDynamicComponentMeta {
+
+    /**
+     * will be used for web component tag, e.g. <my-custom-component>
+     */
+    componentName: string;
+
+    /**
+     * Optional regular expression meant to provide a quick, first pass when
+     * determining what component to inject given a certain route.
+     *
+     * NOTE: This is not the final decider of if the component handles the
+     * route. For that, @see {@link fnHandleRoute}
+     */
+    routeRegExp?: RegExp;
+
+    /**
+     * Optional function that determines if this component should handle a given route.
+     *
+     * If provided **AND IF THE {@link routeRegExp} matches the route path**,
+     * the router will call this function with the route path and the parsed
+     * ibgib address.
+     *
+     * If the component should handle the route, this function will return true,
+     * else false.
+     *
+     * @param {object} arg - Arguments object.
+     * @param {string} arg.path - The route path (from window.location.hash or pathname).
+     * @param {IbGibAddr} [arg.ibGibAddr] - The parsed ibGib address from the route path, if applicable.
+     * @returns {Promise<boolean>} - Promise that resolves to `true` if this component should handle the route, `false` otherwise.
+     *
+     * ## implementation notes
+     *
+     * Since this is an optional property, I define this as a lambda not as a
+     * function proper on the class.
+     */
+    fnHandleRoute?: FnHandleRouteType;
+
+    /**
+     * Factory function to create an instance of the dynamic component.
+     *
+     * @param {object} arg - Arguments object.
+     * @param {string} arg.path - The route path (from window.location.hash or pathname).
+     * @param {IbGibAddr} [arg.ibGibAddr] - The parsed ibGib address from the route path.
+     * @returns {Promise<IbGibDynamicComponentInstance>} - Promise that resolves to a new instance of the dynamic component.
+     */
+    createInstance(arg: {
+        path: string,
+        ibGibAddr: IbGibAddr,
+    }): Promise<IbGibDynamicComponentInstance>;
+
+    /**
+     * factory function that returns a metaspace (most likely a global singleton
+     * service)
+     */
+    fnGetMetaspace: () => Promise<MetaspaceService>;
+    /**
+     * Promise that resolves when the app has initialized ibgib-related code,
+     * e.g., the metaspace.
+     *
+     * ## intent
+     *
+     * I've found that deferring the ibgib-related code can speed up the initial
+     * rendering, but it requires this additional complexity. This is
+     * essentially the ibgib equivalent to waiting for the DOM ready event to
+     * fire.
+     */
+    bootstrapPromise: Promise<void>;
+}
+
+/**
+ * TElements is for the HTML elements of the instance.
+ */
+export interface IbGibDynamicComponentInstance<TIbGib extends IbGib_V1 = IbGib_V1, TElements = any> extends HTMLElement {
+    /**
+     * each instance should have an instance id created in ctor.
+     */
+    get instanceId(): string;
+
+    /**
+     * Meant for HTMLElements that compose this component
+     */
+    elements: TElements | undefined;
+
+    /**
+     * ## driving use case
+     * need an empty ctor for document.createElement call. so createInstance
+     * will use this after creation.
+     */
+    initialize(opts: IbGibDynamicComponentInstanceInitOpts): Promise<void>;
+
+    /**
+     * Reference to the component's meta object that created this component
+     * instance.
+     */
+    meta?: IbGibDynamicComponentMeta;
+
+    /**
+     * Lifecycle method called after the component's HTML is dynamically loaded
+     * and inserted into the DOM.
+     *
+     * Use this to perform component-specific initialization,
+     * e.g., get element references, attach event listeners, set initial state, etc.
+     *
+     * @returns when component is fully created and initialized
+     */
+    created(): Promise<void>;
+    destroyed(): Promise<void>;
+    destroy(): Promise<void>;
+
+    /**
+     * Lifecycle method called when the component is about to be dynamically removed
+     * from the DOM (e.g., when switching tabs or navigating away from the component).
+     *
+     * Use this to perform cleanup tasks,
+     * e.g., unregister event listeners, release resources, save state (if needed), etc.
+     *
+     * @returns when component is fully destroyed and cleaned up
+     */
+    disconnected(): Promise<void>;
+    get ib(): Ib;
+    get gib(): Gib;
+    ibGibAddr: IbGibAddr;
+    /**
+     * The proxy witness used for updating the backing ibGib.
+     */
+    ibGibProxy: LiveProxyIbGib<TIbGib> | undefined;
+    /**
+     * Backing ibgib getter via {@link ibGibProxy.ibGib}
+     */
+    get ibGib(): TIbGib | undefined;
+}
+
+/**
+ * common ctor opts when newing up IbGibDynamicComponentInstanceBase
+ * descendants.
+ *
+ * Extend this interface when adding opts to concrete classes.
+ */
+export interface IbGibDynamicComponentInstanceInitOpts {
+    /**
+     * initial addr that the instance relates to. if you don't have an addr yet,
+     * just pass in {@link ROOT_ADDR} ("ib^gib") which acts like a null object
+     * pattern.
+     */
+    ibGibAddr: IbGibAddr;
+    /**
+     * reference to the meta that creates the instance.
+     */
+    meta: IbGibDynamicComponentMeta;
+    /**
+     * @required The HTML content of the component instance as a string.
+     */
+    html: string;
+    /**
+     * @optional Array of CSS style strings to be loaded with the component.
+     */
+    css?: string[];
+}
+
+/**
+ * Every component is expected to have a content element and frequently a header
+ * and/or footer (but these are optional)
+ */
+export interface ElementsBase {
+    contentEl: HTMLElement;
+    headerEl?: HTMLElement;
+    footerEl?: HTMLElement;
+    /**
+     * often a spinner or something
+     */
+    busyEl?: HTMLElement;
+}
+
+/**
+ * for parent components, this is the base info class that backs a child
+ * component.
+ */
+export interface ChildInfoBase<TComponent extends IbGibDynamicComponentInstance<IbGib_V1>> {
+    /**
+     * for tabbed parents, this is the tab button.
+     * for explorer parents, this is the thing you click to expand/collapse.
+     */
+    childBtnEl: HTMLElement;
+    /**
+     * addr of the child
+     */
+    addr: IbGibAddr;
+    /**
+     * true if the child is active on the parent
+     */
+    active: boolean;
+    /**
+     * if set, this is the agent associated with the child component
+     */
+    agent?: AgentWitnessAny;
+    /**
+     * access the ibGib via this component.
+     *
+     * This component wraps an ibgib proxy that automatically stays up-to-date
+     * when new ibgib frames are added to the ibgib's timeline and published to
+     * the metaspace. (via metaspace.registerNewIbGib)
+     */
+    component?: TComponent;
+}

package/src/ui/component/ibgib-component-service.mts

@@ -0,0 +1,201 @@
+/**
+ * @module component-one-file.mts contains all the types, helpers, constants and
+ * classes for the **shell** ui component system. the differentiating factor
+ * between this system and other front end ui frameworks is that this is
+ * ibgib-driven, with especially ibgib addresses driving components' backing
+ * model/data.
+ *
+ * this is not to be confused with "components" that may be dynamically
+ * generated within a blank-canvas environment that the canvas agents will
+ * build. this is for the old-school html shell.
+ *
+ * the ui component system is being built piecemeal as we go.
+ *
+ * ## approach
+ *
+ * there are two basic pieces to a component: the component metadata declaration
+ * and the concrete component instance that that declaration instantiates. these
+ * will be tightly coupled per use-case, with the intention that the meta object
+ * will not need to be a descendant class, whereas the component instance will
+ * most likely be the class that is extended from an abstract base class.
+ *
+ * @see {@link IbGibDynamicComponentMeta}
+ * @see {@link IbGibDynamicComponentInstance}
+ */
+
+import { extractErrorMsg, } from "@ibgib/helper-gib/dist/helpers/utils-helper.mjs";
+import { IbGibAddr } from "@ibgib/ts-gib/dist/types.mjs";
+
+import { GLOBAL_LOG_A_LOT } from "../../constants.mjs";
+import { IbGibDynamicComponentInstance, IbGibDynamicComponentMeta } from "./component-types.mjs";
+
+const logalot = GLOBAL_LOG_A_LOT;
+/**
+ * Service for managing dynamic ibgib-aware components via web components.
+ */
+export class IbGibComponentService {
+    protected lc: string = `[${IbGibComponentService.name}]`;
+    /**
+     * @internal references to component meta's registered with the service.
+     */
+    private _registeredComponentsMeta: IbGibDynamicComponentMeta[] = [];
+
+    initialized: Promise<void>;
+
+    constructor() {
+        this.initialized = this.initialize();
+    }
+
+    private async initialize(): Promise<void> {
+        const lc = `[${this.initialize.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: 1cf04e8d768f4b5c55e7c3861e2d2225)`); }
+            console.log(`${lc} does nothing atow (I: 65bb46c88c82b637ad928b8bf1a07225)`)
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+
+    /**
+     * Registers a dynamic ibgib-aware component META object with the service.
+     * @param {IbGibDynamicComponentMeta} componentMeta - The component meta object to register.
+     */
+    registerComponentMeta(componentMeta: IbGibDynamicComponentMeta): void {
+        this._registeredComponentsMeta.push(componentMeta);
+        if (logalot) { console.log(`${this.lc}[registerComponentMeta] component meta registered: ${componentMeta.constructor.name} (I: 88ddcbd0c8caa2342af0e7348f171225)`); }
+    }
+
+    /**
+     * Unregisters a dynamic ibgib-aware component META object from the service.
+     * @param {IbGibDynamicComponentMeta} componentMeta - The component meta object to unregister.
+     */
+    unregisterComponentMeta(componentMeta: IbGibDynamicComponentMeta): void {
+        this._registeredComponentsMeta = this._registeredComponentsMeta.filter(c => c !== componentMeta);
+        if (logalot) { console.log(`${this.lc}[unregisterComponentMeta] component meta unregistered: ${componentMeta.constructor.name} (I: 4e84b5274de688248984896a90f5cc25)`); }
+    }
+
+    async getComponentInstance({
+        useRegExpPrefilter,
+        path,
+        ibGibAddr,
+    }: {
+        useRegExpPrefilter: boolean,
+        path: string,
+        ibGibAddr: IbGibAddr,
+    }): Promise<IbGibDynamicComponentInstance | undefined> {
+        const lc = `${this.lc}[${this.getComponentInstance.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: 684ef316cbdb4a3b1fdc96096c273b25)`); }
+
+            let componentToInject: IbGibDynamicComponentInstance | undefined = undefined;
+
+            // 1. Get registered components from the component service (NEW)
+            const registeredComponents = componentSvc.getRegisteredComponentsMeta();
+
+            // 2. Filter by routeRegExp (quick filter)
+            const possibleComponentsMeta = useRegExpPrefilter ?
+                registeredComponents.filter(component => {
+                    const componentMatchesPath = component.routeRegExp ? component.routeRegExp.test(path) : false;
+                    if (logalot) { console.log(`${lc} ${component.componentName} ${component.routeRegExp} componentMatchesPath: ${componentMatchesPath} (I: 3758520e6a4a57f218396c8649283425)`); }
+                    return componentMatchesPath;
+                }) :
+                registeredComponents.concat();
+
+            // 3. Iterate and call fnHandleRoute for finer-grained check
+            for (const componentMeta of possibleComponentsMeta) {
+                /**
+                 * order of component registration wins right now
+                 */
+                const componentHandlesPath = componentMeta.fnHandleRoute ?
+                    await componentMeta.fnHandleRoute({ path, ibGibAddr }) :
+                    true;
+                if (componentHandlesPath) {
+                    componentToInject = await componentMeta.createInstance({
+                        path, ibGibAddr,
+                    });
+                    break; // Stop on first component that handles the route
+                }
+            }
+
+            return componentToInject;
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+
+    /**
+     * Injects a dynamic ibgib-aware component into a parent HTML element based on the route path.
+     *
+     * @param {object} arg - Arguments object.
+     * @param {HTMLElement} arg.parentEl - The parent HTML element where the component should be injected.
+     * @param {string} arg.path - The route path to determine which component to load.
+     * @param {IbGibAddr} [arg.ibGibAddr] - Optional ibGib address parsed from the route path.
+     * @returns {Promise<void>} - Promise that resolves when the component is injected and created.
+     */
+    async inject({
+        parentEl,
+        componentToInject,
+    }: {
+        parentEl: HTMLElement,
+        componentToInject: IbGibDynamicComponentInstance,
+    }): Promise<void> {
+        const lc = `${this.lc}[${this.inject.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: 6844cf07eaf8a5b1b106784f7db17125)`); }
+
+            if (!parentEl) { throw new Error(`${lc} parentEl required. (E: 6f4eb2d682856ef47d173b970ec3c825)`); }
+            if (!componentToInject) { throw new Error(`${lc} componentToInject required. (E: decf0b51ad49257ce44fecbcf84c3a25)`); }
+            if (!componentToInject.meta) { throw new Error(`${lc} componentToInject.meta required. (E: f8827c0602ca7b0e030d0b3e2c4a4825)`); }
+            if (!componentToInject.meta.componentName) { throw new Error(`${lc} componentToInject.meta.componentName required. (E: 5dcae244ae32690f7b73ce27a32a3c25)`); }
+
+            // Clear parent content
+            parentEl.innerHTML = '';
+
+            // attach the component (web component) to the parent
+            parentEl.appendChild(componentToInject);
+
+            // right now we're manually fading in/out with this kluge.
+            parentEl.classList.remove('fade-out');
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            parentEl.innerHTML = `<p class="error">Error loading component for route. error:</p><br /><br /><p>${error.message}</p>`;
+            // console.error(`${lc} ${extractErrorMsg(error)}`);
+            // throw error; // Re-throw error for upstream handling
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+
+    getRegisteredComponentsMeta(): readonly IbGibDynamicComponentMeta[] {
+        return [...this._registeredComponentsMeta];
+    }
+}
+
+/**
+ * Singleton instance of the IbGibComponentService.
+ */
+let componentSvc: IbGibComponentService;
+export async function getComponentSvc(): Promise<IbGibComponentService> {
+    const lc = `[${getComponentSvc.name}]`;
+    try {
+        if (logalot) { console.log(`${lc} starting... (I: 853694c88223381339103a3765129925)`); }
+
+        if (!componentSvc) {
+            componentSvc = new IbGibComponentService();
+            await componentSvc.initialized;
+        }
+
+        return componentSvc;
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    } finally {
+        if (logalot) { console.log(`${lc} complete.`); }
+    }
+}