@ibgib/web-gib 0.0.1

package/dist/helpers.web.d.mts

@@ -0,0 +1,324 @@
+/**
+ * @module helpers.web
+ *
+ * helper functions specific to the web version.
+ */
+import { IbGib_V1 } from "@ibgib/ts-gib/dist/V1/types.mjs";
+import { Gib, IbGibAddr } from "@ibgib/ts-gib/dist/types.mjs";
+import { MetaspaceService } from "@ibgib/core-gib/dist/witness/space/metaspace/metaspace-types.mjs";
+import { RawExportIbGib_V1 } from "@ibgib/core-gib/dist/common/import-export/import-export-types.mjs";
+import { FlatIbGibGraph } from "@ibgib/core-gib/dist/common/other/graph-types.mjs";
+import { IbGibSpaceAny } from "@ibgib/core-gib/dist/witness/space/space-base-v1.mjs";
+import { GibColorInfo } from "./types.web.mjs";
+/**
+ * converts string to Uint8Array.
+ * @param str to convert
+ * @returns array
+ */
+export declare function stringToUint8Array(str: string): Uint8Array;
+/**
+ * converts Uint8Array to string.
+ * @param array to convert
+ * @returns string
+ */
+export declare function uint8ArrayToString(array: Uint8Array): string;
+/**
+ * I'm pulling out node from @ibgib/ibgib rcli code. This interface is just to
+ * aid in that transition.
+ */
+export interface PathUtilsHelper {
+    isAbsolute(path: string): boolean;
+    isRelative(path: string): boolean;
+    join(...paths: string[]): string;
+    dirname(path: string): string;
+    basename(path: string, ext?: string): string;
+}
+/**
+ * Helper class that exposes pathUtils functions. Note that this is relative to
+ * an individual space.
+ */
+export declare class PathUtilsHelper implements PathUtilsHelper {
+    /** class-level log context */
+    lc: string;
+    /**
+     *
+     */
+    /**
+     *
+     */
+    constructor();
+}
+export declare function copyToClipboard({ data, logalot, }: {
+    data: {
+        title?: string;
+        text?: string;
+        url?: string;
+    };
+    logalot?: boolean;
+}): Promise<void>;
+/**
+ * helper to trigger browser's share functionality (or fallback).
+ */
+export declare function shareContent({ data, logalot, }: {
+    data: {
+        title?: string;
+        text?: string;
+        url?: string;
+    };
+    logalot?: boolean;
+}): Promise<void>;
+/**
+ * useful for knowing if we are executing in our website or within an iframe.
+ *
+ * ## driving use case
+ *
+ * When we are loading an embedded iframe for link-gib, it is trying to trigger
+ * the router which is no bueno.
+ *
+ * This is causing a problem though when testing inside an iframe in Project
+ * IDX...I guess I'll have to whitelist embedded sites like link-gib
+ *
+ * @returns true if we are executing in an iframe, false otherwise.
+ */
+export declare function isExecutingInBlankGibWebAppProper({ metaName_appId, metaContent_appId }: {
+    /**
+     * this runs code:
+     *
+     * `const metaElement = document.querySelector(`meta[name=${metaName_appId}]`) as (HTMLMetaElement | null);`
+     *
+     * in the index, you should tag the meta tag with attribute of this.
+     */
+    metaName_appId: string;
+    /**
+     * this is an appId on the `metaElement.content`
+     */
+    metaContent_appId: string;
+}): boolean;
+/**
+ * Low-level plumbing for prompting the user for some text.
+ *
+ * ## notes
+ *
+ * * if an empty string is entered, confirm is automatic/always happens.
+ * * if confirm is true, will confirm on any entry
+ * * can just hit ENTER to confirm anything
+ *   * this should be parameterized
+ *
+ * @returns the text the user entered.
+ */
+export declare function promptForText({ msg, title, confirm, noNewLine, rl, defaultValue, dontCloseRl, cancelable, }: {
+    msg: string;
+    title?: string;
+    confirm?: boolean;
+    noNewLine?: boolean;
+    /**
+     * ignored in web version. used in node version. this is after all, a hack
+     * port
+     */
+    rl?: any;
+    defaultValue?: string;
+    /**
+     * ignored in web version. used in node version. this is after all, a hack
+     * port
+     */
+    dontCloseRl?: boolean;
+    /**
+     * if true, cancel will show and an empty string will be returned
+     */
+    cancelable?: boolean;
+}): Promise<string>;
+/**
+ * not implemented atow (12/2024). I think we'll have perhaps a modal dialog
+ * with a known name and get at it that way.
+ */
+export declare function promptForSecret({ msg, confirm, }: {
+    msg?: string;
+    confirm: boolean;
+}): Promise<string>;
+/**
+ * prompt specifically looking to confirm something. if "cancelled", returns
+ * false.
+ */
+export declare function promptForConfirm({ msg, yesLabel, noLabel, }: {
+    /**
+     * if provided, this is the message displayed when confirming.
+     */
+    msg?: string;
+    yesLabel?: string;
+    noLabel?: string;
+}): Promise<boolean>;
+export declare function alertUser({ msg, title, skipHitEnterToContinue, }: {
+    msg: string;
+    title?: string;
+    /**
+     * ignored in web version atow (12/2024)
+     */
+    skipHitEnterToContinue?: boolean;
+}): Promise<void>;
+export declare function getUserPreferredColorScheme(): 'light' | 'dark';
+/**
+ * helper function to get a query param in the current url.
+ *
+ * # ONLY IN BROWSER
+ *
+ * not for use in node.js
+ *
+ * @returns raw
+ */
+export declare function getQueryParam<TValue>({ paramName, parseJSON, logalot, }: {
+    paramName: string;
+    parseJSON?: boolean;
+    logalot?: boolean;
+}): TValue | undefined;
+/**
+ * helper function to set a query param in the current url.
+ *
+ * # ONLY IN BROWSER
+ *
+ * not for use in node.js
+ */
+export declare function setQueryParam<TValue>({ paramName, paramValue, rmParam, logalot, }: {
+    paramName: string;
+    paramValue?: TValue;
+    /**
+     * if true, we will remove the param from the URL.
+     */
+    rmParam?: boolean;
+    logalot?: boolean;
+}): void;
+/**
+ * helper to highlight an element with border/background.
+ *
+ * ## requires
+ *
+ * .highlight and .unhighlight classes
+ *
+ * The unhighlight is for correctly showing the transition/animation.
+ *
+ * ## intent
+ *
+ * Just making this to make highlighting things (drawing the user's eye)
+ * easier and more consistent.
+ *
+ * @see {@link unhighlightElement}
+ */
+export declare function highlightElement({ el, magicHighlightTimingMs, scrollIntoView, }: {
+    el: HTMLElement;
+    /**
+     * if provided, will unhighlight the element after this delay in ms
+     */
+    magicHighlightTimingMs?: number;
+    scrollIntoView?: boolean;
+}): Promise<void>;
+/**
+ * @see {@link highlightElement}
+ */
+export declare function unhighlightElement({ el, }: {
+    el: HTMLElement;
+}): Promise<void>;
+/**
+ * builds a color schema based on the gib.
+ *
+ * note that the alpha drives the translucent property, but the solid color is
+ * always built
+ */
+export declare function getDeterministicColorInfo({ ibGibAddr, gib, ibGib, translucentAlpha, }: {
+    ibGibAddr?: IbGibAddr;
+    gib?: Gib;
+    ibGib?: IbGib_V1;
+    /**
+     * drives the translucent color.
+     *
+     * @default 10
+     */
+    translucentAlpha?: number;
+}): GibColorInfo;
+/**
+ * gets the color, colorTranslucent and colorContrast
+ */
+export declare function getColorStrings(translucentAlpha: number, drivingHash: string): [string, string, string];
+/**
+ * Takes an incoming string. Assumes it's invalid. Does best effort at validating this.
+ * Gets the raw export ibgib if it can. If so, and if it is compressed, decompresses the
+ * compressed graph contained in the export ibgib.
+ *
+ * @returns RawExportIbGib_V1 and its decompressed graph
+ */
+export declare function getRawExportIbGibAndGraphFromJsonString({ exportIbGibJsonString, metaspace, }: {
+    exportIbGibJsonString: string;
+    metaspace: MetaspaceService;
+}): Promise<[RawExportIbGib_V1, FlatIbGibGraph]>;
+/**
+ * exports a given ibgib to the default local userspace in the metaspace.
+ */
+export declare function exportIbGib({ ibGib, compress, metaspace, space, }: {
+    ibGib: IbGib_V1;
+    compress: boolean;
+    metaspace: MetaspaceService;
+    space: IbGibSpaceAny;
+}): Promise<void>;
+export declare function promptForAPIKey({ msg, }: {
+    /**
+     * msg to tell the user when prompting for the API key (secret)
+     *
+     * originally in blankgib, this is CHAT_WITH_AGENT_NEED_API_KEY
+     */
+    msg: string;
+}): Promise<string | undefined>;
+/**
+ * updates the given {@link apiKey}. if {@link force} is true and `apiKey` is
+ * empty, then this will set an empty string for the apiKey, effectively
+ * deleting it.
+ */
+export declare function updateAPIKeyInStorage({ dbName, storeName, key, apiKey, force, }: {
+    dbName: string;
+    storeName: string;
+    key: string;
+    apiKey: string;
+    force: boolean;
+}): Promise<void>;
+/**
+ * wrapper for simplifying/asserting an element that is expected to exist.
+ *
+ * ## intent
+ *
+ * This avoids using TypeScript truthy assertions (!) or excessive
+ * falsy/exception checks.
+ */
+export declare function getElementById_throwsIfFalsy<TElement extends Element>({ id, shadowRoot, }: {
+    id: string;
+    /**
+     * If set, will get element here, else will use document
+     */
+    shadowRoot?: ShadowRoot;
+}): TElement;
+/**
+ * wrapper that throws if element not found.
+ * @param id of Element
+ * @returns Element of type TElement or throws.
+ * @see {@link shadowRoot_getElementById}
+ *
+ * ## intent
+ *
+ * This avoids using TypeScript truthy assertions (!) or excessive
+ * falsy/exception checks.
+ */
+export declare function document_getElementById<TElement extends Element = HTMLElement>(id: string): TElement;
+/**
+ * wrapper that throws if element not found.
+ * @param shadowRoot in which the element MUST be truthy or throws
+ * @param id of Element
+ * @returns Element of type TElement or throws.
+ * @see {@link document_getElementById}
+ *
+ * ## intent
+ *
+ * This avoids using TypeScript truthy assertions (!) or excessive
+ * falsy/exception checks.
+ */
+export declare function shadowRoot_getElementById<TElement extends Element = HTMLElement>(shadowRoot: ShadowRoot, id: string): TElement;
+export declare function getGlobalMetaspace_waitIfNeeded(): Promise<MetaspaceService>;
+export declare function getGlobalStoreName(): Promise<string>;
+export declare function getGlobalDbName(): string;
+export declare function getGlobalIndexedDbKey_APIKey(): Promise<string>;
+//# sourceMappingURL=helpers.web.d.mts.map

package/dist/helpers.web.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.web.d.mts","sourceRoot":"","sources":["../src/helpers.web.mts"],"names":[],"mappings":"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"}