@osqd/bothandlerjs 0.3.0 → 0.5.0

package/dist/element/index.d.ts

@@ -0,0 +1,137 @@
+/**
+ * `<bot-dashboard>` — the operator dashboard as an element you drop into your own page.
+ *
+ * ```html
+ * <bot-dashboard src="/_bots"></bot-dashboard>
+ * <script type="module">
+ *   import { defineBotDashboard } from "@osqd/bothandlerjs/element";
+ *   defineBotDashboard();
+ * </script>
+ * ```
+ *
+ * The data still comes from a mounted handler — `createDashboardHandler(botHandler, {
+ * basePath: "/_bots" })` — because there is nowhere else for it to come from. What the
+ * element removes is having to build, style and route a page around it.
+ *
+ * ## What running it in your page costs you
+ *
+ * This renders into a shadow root inside your document, which is what makes it sit in
+ * your layout rather than in a frame. The shadow root is a styling boundary and **not a
+ * security boundary**: any script that can run on the host page can reach into it, read
+ * every visitor address and verdict on screen, and call the dashboard's API with your
+ * credentials. On the standalone page an injected script in your application could do
+ * none of that.
+ *
+ * So mount it on a page that is already behind your admin authentication, and treat an
+ * XSS on that page as equivalent to handing over the dashboard. If you would rather have
+ * the isolation than the layout, serve the standalone page instead — it is the same
+ * dashboard, and `createDashboardHandler` already returns it.
+ */
+import type { BotDashboardConfig, BotDashboardPanel, BotDashboardRows, BotDashboardTab, BotDashboardTabId, BotDashboardTheme } from "./config.js";
+/** One screen of the dashboard. */
+export type { BotDashboardConfig, BotDashboardPanel, BotDashboardRows, BotDashboardTab, BotDashboardTabId, BotDashboardTheme };
+/**
+ * Registers `<bot-dashboard>`. Safe to call more than once.
+ *
+ * @param name - element name, if `bot-dashboard` is taken.
+ */
+export declare function defineBotDashboard(name?: string): void;
+/**
+ * `HTMLElement`, or a stand-in where there is no DOM.
+ *
+ * `class X extends HTMLElement` is evaluated when the module is *loaded*, not when the
+ * element is used — so on a server, where there is no `HTMLElement`, merely importing this
+ * file threw `ReferenceError` before a line of anyone's code ran. That is not an exotic
+ * case: it is what every framework with server rendering does with a top-level
+ * `import { defineBotDashboard } from "@osqd/bothandlerjs/element"`, which is exactly the
+ * line the documentation tells people to write.
+ *
+ * `defineBotDashboard` already declines to do anything without a `customElements`
+ * registry, so the intent was there; the class declaration simply ran first. With this the
+ * module imports anywhere, and does nothing at all until it is in a browser.
+ */
+declare const ElementBase: typeof HTMLElement;
+export declare class BotDashboardElement extends ElementBase {
+    private settings;
+    private booted;
+    /**
+     * Booted *and* finished drawing. Distinct from `booted`, which is set on the way in:
+     * `connectedCallback` replays a config assigned before the upgrade through the setter,
+     * and at that moment `booted` is already true — so a warning keyed on it fired on a
+     * perfectly ordinary mount, complaining that the config had changed when what had
+     * happened was that it had arrived.
+     */
+    private rendered;
+    /**
+     * Set before the element is attached, or pass the same things as attributes.
+     *
+     * An accessor rather than a field, and the difference is load-bearing. A page that
+     * writes `el.config = {...}` before the element is defined puts an *own property* on
+     * the instance, and a class field initialiser then runs at upgrade and overwrites it —
+     * so the configuration silently disappears and the dashboard renders its defaults. The
+     * accessor plus the upgrade dance in `connectedCallback` is the documented way round
+     * it, and the order it protects (write the config, then define the element) is the
+     * natural one to write.
+     */
+    get config(): BotDashboardConfig;
+    set config(value: BotDashboardConfig);
+    private timers;
+    /** Custom properties this element put on itself, so it can take them off again. */
+    private appliedTokens;
+    private warned;
+    static get observedAttributes(): string[];
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(attribute: string, previous: string | null, value: string | null): void;
+    /**
+     * Give up on this attempt without giving up on the element.
+     *
+     * Every way a boot can end early — it lost the one-at-a-time race, its `src` is
+     * cross-origin, its handler did not answer, it was unmounted mid-flight — is about this
+     * moment rather than about this element, and all four are things a remount can fix: the
+     * other dashboard has gone, the attribute was corrected, the server finished starting.
+     * Releasing ownership without clearing `booted` was the bug: `connectedCallback` returns
+     * early on a latched `booted`, so the element stayed dead for the life of the instance
+     * and a router that remounts it drew a stale error over a handler that now works.
+     */
+    private standDown;
+    /**
+     * Where the handler is mounted, from `config.src` or the attribute.
+     *
+     * A trailing slash is dropped, and so are a query string and a fragment — the element
+     * appends `/api/bootstrap` to this, so anything after the path cannot survive that
+     * concatenation and never could. Left in, `src="/_bots?token=x"` failed with "it
+     * answered text/html — is createDashboardHandler mounted at /_bots?token=x?", which
+     * sends somebody to check the one thing that was right.
+     */
+    private mountPath;
+    private boot;
+    private applyTheme;
+    /**
+     * `scheme` and `density` take two values each, and until now anything else was accepted
+     * in silence — a mis-typed `scheme` did nothing, and a mis-typed `density` was written
+     * onto the element as `data-density="cozy"`, matching no rule and looking, from the
+     * outside, exactly like a dashboard that ignores its configuration.
+     *
+     * Warned once per bad value per element, because `applyTheme` runs on every re-render
+     * and a typo that repeats a hundred times is a typo the console has stopped conveying.
+     */
+    private applyScheme;
+    private applyDensity;
+    private warnOnce;
+    /**
+     * Reorders and relabels the strip the client has just drawn.
+     *
+     * Only the tabs that survived: which screens *exist* was settled in the boot object
+     * before the client ran, because the client builds its list from there and looks each
+     * one up by id — deleting an element here instead crashed it with "no element
+     * #tab-actors", which is what this comment is standing in for.
+     */
+    private relabelTabs;
+    private renderPanels;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        "bot-dashboard": BotDashboardElement;
+    }
+}