@lo-tek/interfaces 0.0.0 → 0.38.0

package/dist/components/host-element.js

@@ -0,0 +1,440 @@
+/**
+ * The base the web components inherit from, and their registration.
+ *
+ * `HTMLElement` and `customElements` only exist in the browser. A
+ * `class X extends HTMLElement` is evaluated when the module loads, so a
+ * server that only wanted `lt.button()` from the package stopped with
+ * "HTMLElement is not defined" before it got that far. That hit nine of the
+ * entry points, the main entry included, and made the package useless in
+ * exactly the situation it is built for: the server writing the markup.
+ *
+ * The fallback is an empty class. It is never used for anything, because
+ * without `customElements` nothing is registered, and without registration
+ * the browser never creates an instance. It only exists so the module can
+ * load.
+ */
+export const HostElement = typeof HTMLElement === "undefined"
+    ? class {
+    }
+    : HTMLElement;
+/**
+ * Registers a web component, once, and only in the browser.
+ *
+ * When `defineLt*` is called from a module that also runs on the server, as
+ * in TanStack Start or a server-rendered React app, nothing happens. There is
+ * no `customElements` there to register in.
+ *
+ * A constructor can only be in the registry once. If the class is already
+ * there under another name, a subclass is registered:
+ * `defineLtToast("app-toast")` followed by `defineLt()` otherwise threw
+ * NotSupportedError on `lt-toast`, and the components after it in the list
+ * were never registered. With the subclass both names work, and `instanceof`
+ * holds for both.
+ */
+export function defineElement(tagName, element) {
+    if (typeof customElements === "undefined")
+        return;
+    if (customElements.get(tagName))
+        return;
+    if (isRegistered(element)) {
+        customElements.define(tagName, class extends element {
+        });
+        return;
+    }
+    try {
+        customElements.define(tagName, element);
+    }
+    catch (error) {
+        // The fallback for browsers without `getName`: the name is free, so a
+        // NotSupportedError here means the constructor is already in use.
+        if (!(error instanceof DOMException && error.name === "NotSupportedError"))
+            throw error;
+        customElements.define(tagName, class extends element {
+        });
+    }
+}
+/**
+ * Whether the constructor is already in the registry, under any name.
+ * `getName` arrived in Chrome 117, Firefox 116 and Safari 17; without it the
+ * answer is `false`, and `define` reports the problem itself.
+ */
+function isRegistered(element) {
+    if (typeof customElements.getName !== "function")
+        return false;
+    return customElements.getName(element) !== null;
+}
+/**
+ * Sets an attribute, but only when the value actually differs.
+ *
+ * The components observe the attributes they set themselves, so they can set
+ * them back after a patch. Writing a value that is already there counts as a
+ * change, so the observer calls itself, writes again, and the microtask queue
+ * never empties. The page freezes, and a test run hangs without an error: no
+ * stack trace, no assertion, just silence. That is why no test can catch it,
+ * and why writes go through one function all the components use.
+ *
+ * `null` removes the attribute.
+ */
+export function setAttr(element, name, value) {
+    if (value === null || value === undefined) {
+        if (element.hasAttribute(name))
+            element.removeAttribute(name);
+    }
+    else if (element.getAttribute(name) !== value) {
+        element.setAttribute(name, value);
+    }
+}
+/**
+ * The attribute a component marks what it wrote with: the names of the
+ * attributes on the element whose value is the component's, separated by
+ * spaces.
+ *
+ * Some attributes are both the server's and the component's: `aria-invalid`
+ * on a field, `aria-selected` on a tab. To tell the server's word from its
+ * own echo, a component remembered the value it wrote, and read anything
+ * else as the server's. A server that sent the same value was never seen: a
+ * morph does not touch an attribute whose value is already right, and the
+ * component took the server's `aria-invalid="true"` for its own and removed
+ * it. The mark is what a morph does touch. The server never sends it, so a
+ * morph from the server removes it, and an attribute without the mark is the
+ * server's, whatever its value. A script that changes the element without a
+ * morph leaves the mark, and is seen as before, by the value.
+ *
+ * Only what differs from the server's word is marked. A value that is the
+ * server's has nothing to tell apart, and markup that is already right, as
+ * React renders `lt.tabs()` with the state, must not be touched: hydration
+ * reports every attribute it did not render.
+ */
+export const WRITTEN = "data-lt-written";
+/**
+ * Marks `name` on `element` as the component's when `mine`, that is, when
+ * what the component wrote differs from the server's word, and removes the
+ * mark otherwise.
+ */
+export function markWritten(element, name, mine) {
+    const marked = new Set((element.getAttribute(WRITTEN) ?? "").split(/\s+/).filter(Boolean));
+    if (mine)
+        marked.add(name);
+    else
+        marked.delete(name);
+    setAttr(element, WRITTEN, marked.size > 0 ? [...marked].sort().join(" ") : null);
+}
+/**
+ * Warns when `element` carries the mark before the component has written on
+ * it: the mark is in the markup it was given, copied into a template from
+ * the browser's developer tools. A morph then never removes it, and the
+ * component takes the server's word for its own echo again. Called where the
+ * component meets the element for the first time; the check cannot wait, so
+ * the warning is not checked again when the page has settled.
+ */
+export function warnAboutCopiedMark(host, element) {
+    if (!element.hasAttribute(WRITTEN))
+        return;
+    warnAboutMarkup(host, `found ${WRITTEN} in the markup it was given. The browser writes the ` +
+        "attribute to tell the component's own values from the server's; " +
+        "copied into a template, it makes the component take what the " +
+        "server sends for its own. Remove it from the template.", () => true);
+}
+/**
+ * Whether the component's mark for `name` is still on `element`: no morph
+ * from the server has been there since the component wrote it.
+ */
+export function stillMarked(element, name) {
+    return (element.getAttribute(WRITTEN) ?? "").split(/\s+/).includes(name);
+}
+/**
+ * Turns a boolean attribute on or off, without writing when it is already so.
+ *
+ * `el.hidden = true` on something already hidden writes the attribute again,
+ * and that counts as a change. `toggleAttribute` does not: if the attribute
+ * is already as it should be, nothing happens. So it is the only permitted
+ * way to `hidden`, `disabled` and the other boolean attributes in a component
+ * that observes the attributes it writes.
+ *
+ * `Boolean(on)` and not `on` alone: with `undefined` as the second argument
+ * `toggleAttribute` toggles instead of removing. React 19 writes
+ * `el.open = undefined` when a prop goes from `true` to absent, and the
+ * setter then put the attribute back: a dialog the user had closed opened
+ * again as the app followed along.
+ */
+export function setFlag(element, name, on) {
+    element.toggleAttribute(name, Boolean(on));
+}
+/**
+ * The language nearest the element, or `undefined` when the page does not
+ * say.
+ *
+ * `undefined` gives `Intl` the browser's language. A `lang` that is not a
+ * valid language tag makes `Intl` throw, and then the browser's language is
+ * better than no text.
+ */
+export function languageOf(element) {
+    /*
+     * `closest()` stops at a shadow root. If the element is in one, as in
+     * every preview in the documentation, the search continues from the host;
+     * otherwise it never found `lang` on `<html>`.
+     */
+    let node = element;
+    while (node) {
+        const owner = node.closest("[lang]");
+        // `lang=""` means "unknown language" and stops inheritance from the ancestors.
+        if (owner) {
+            const lang = owner.getAttribute("lang")?.trim();
+            if (!lang)
+                return undefined;
+            try {
+                Intl.getCanonicalLocales(lang);
+                return lang;
+            }
+            catch {
+                return undefined;
+            }
+        }
+        const root = node.getRootNode();
+        node = root instanceof ShadowRoot ? root.host : null;
+    }
+    return undefined;
+}
+/**
+ * Writes text in an element, but only when the text differs.
+ *
+ * `textContent` is a `childList` change, and the components observe their
+ * children. Writing the same text again counts as a change, and then the
+ * observer calls itself.
+ *
+ * `textContent` is all the text in the subtree joined, so the comparison does
+ * not tell `<b>3</b> matches` from `3 matches`. The function is meant for
+ * elements the component fills with plain text, such as the match count in
+ * the suggestion field.
+ */
+export function setText(element, text) {
+    if (element.textContent !== text)
+        element.textContent = text;
+}
+/** Adds a class, but only when it is not already there. */
+export function addClass(element, name) {
+    if (!element.classList.contains(name))
+        element.classList.add(name);
+}
+/** An id the component creates itself, when the markup had none. */
+export function uniqueId(prefix) {
+    return `${prefix}-${Math.random().toString(36).slice(2, 9)}`;
+}
+/**
+ * The id an element should have: the one it has, otherwise the one the
+ * component created for that node before. A morph keeps the node and tears
+ * the id off, and it gets the same one back, so a screen reader does not
+ * follow a reference that changes under it.
+ */
+export function rememberedId(memory, element, prefix) {
+    if (element.id)
+        return element.id;
+    let id = memory.get(element);
+    if (!id) {
+        id = uniqueId(prefix);
+        memory.set(element, id);
+    }
+    return id;
+}
+/**
+ * The parts with a role, and those without only when the component set the
+ * roles itself.
+ *
+ * The components fill in roles where the markup came without them: a button
+ * in the row becomes a tab, an `<li>` in the list becomes an option. But if
+ * the server wrote the roles, an element without a role is something else,
+ * such as a "close" button in the row, and must not get a role, an id and
+ * `tabindex="-1"` from the component. `roledByHost` holds the roles the
+ * component set itself: if every role present was set by the component, the
+ * markup is bare, and an element without a role that the server sends later
+ * is a new part. The parts are limited to the host, since components inside
+ * components are ordinary markup.
+ */
+export function derivedParts(host, selector, role, roledByHost) {
+    const own = [...host.querySelectorAll(selector)].filter((part) => part.closest(host.localName) === host);
+    const bare = own
+        .filter((part) => part.getAttribute("role") === role)
+        .every((part) => roledByHost.has(part));
+    return bare ? own : own.filter((part) => part.getAttribute("role") === role);
+}
+/**
+ * The attribute that gives the state back to the server.
+ *
+ * By default the components repair what the user has done: the selected tab,
+ * the open popover, the expanded suggestion list. A morph tears it away,
+ * since none of it was in the HTML the server sent, and the component sets it
+ * back. Then no template needs to know the attributes.
+ *
+ * Sometimes the server should decide: "go on to step 2" is a real thing a
+ * server wants to be able to do. With `server-controlled` on the host, the
+ * component does not set back what the user did, and each patch decides. It
+ * still does the wiring and the keyboard, and what the attribute means for
+ * each component is documented in the component.
+ *
+ * This replaces `data-preserve-attr`, which required the template to copy the
+ * name of every attribute the component would touch. One attribute to
+ * remember instead of nine, and the default is the right choice almost
+ * always.
+ *
+ * Preserving is also a mechanism of one particular morpher:
+ * `data-preserve-attr` is a `data-*` attribute, and such an attribute only
+ * means something to the code that reads it. Repair reads the markup, and
+ * works whoever does the morphing.
+ */
+export const SERVER_CONTROLLED = "server-controlled";
+/** Whether the server decides the state in this element. */
+export function isServerControlled(element) {
+    return element.hasAttribute(SERVER_CONTROLLED);
+}
+/**
+ * Warns when the markup a component received does not fit together.
+ *
+ * A component that cannot find its parts cannot do its job, and the only
+ * alternative to a message is silence. It was silent for a long time: a
+ * template without a control in `<lt-field>` gave a field without wiring,
+ * and nothing said so until someone read the page with a screen reader.
+ *
+ * The message comes once per element and message. A component syncs on every
+ * patch, and a warning per patch would fill the console so fast it became
+ * useless. So the message must be the same every time: interpolate a number
+ * into it and every round is a new message, and the deduplication is gone.
+ *
+ * `stillBroken` is why the warning can be trusted. It is called again when
+ * the page has settled, and only then is anything written. A component sees
+ * its markup as it connects, and the markup is often unfinished then: HTML
+ * streamed from a Go or Kotlin server arrives in chunks, and a break between
+ * the label and the field is perfectly normal. Without the final check the
+ * component warned about markup that was fine a moment later, and a warning
+ * that also fires on correct markup gets switched off.
+ *
+ * It comes in every environment, not only during development. The package
+ * has no build step that could remove it, and a warning that only fires on
+ * markup that really is wrong belongs where it happens.
+ */
+const reported = new WeakMap();
+const queued = new WeakMap();
+export function warnAboutMarkup(element, message, stillBroken) {
+    if (typeof console === "undefined")
+        return;
+    if (reported.get(element)?.has(message))
+        return;
+    let pending = queued.get(element);
+    if (!pending) {
+        pending = new Set();
+        queued.set(element, pending);
+    }
+    if (pending.has(message))
+        return;
+    pending.add(message);
+    whenSettled(() => {
+        pending.delete(message);
+        if (!element.isConnected || !stillBroken())
+            return;
+        let said = reported.get(element);
+        if (!said) {
+            said = new Set();
+            reported.set(element, said);
+        }
+        if (said.has(message))
+            return;
+        said.add(message);
+        console.warn(`${element.tagName.toLowerCase()}: ${message}`, element);
+    });
+}
+/**
+ * Runs once the page has settled.
+ *
+ * First the parser must be done, or we only see the part of the markup that
+ * has arrived so far. Then two frames, so a morph, a React hydration or a
+ * script that fills the element in the next task has time to finish first.
+ */
+function whenSettled(run) {
+    let done = false;
+    const once = () => {
+        if (done)
+            return;
+        done = true;
+        run();
+    };
+    const afterTwoFrames = () => {
+        if (typeof requestAnimationFrame === "undefined") {
+            once();
+            return;
+        }
+        /*
+         * A fallback, because `requestAnimationFrame` does not always fire in a
+         * frame that is not painted. Tested in an `<iframe>` with
+         * `display: none`: Chromium and WebKit fire anyway, Firefox does not.
+         * Without the fallback the message stayed in the queue there for ever,
+         * and blocked a later, real warning about the same thing.
+         *
+         * It is not cancelled. An attempt to cancel it in the first frame was
+         * worse than the problem: if the first frame fires and the tab is hidden
+         * before the second, both the fallback and the second frame are gone,
+         * and the check never runs. `once` runs only once, so it does no harm
+         * that both paths are running, and whichever comes first wins.
+         *
+         * One second is chosen so two frames win in anything but a page that is
+         * completely stalled. If that happens, a warning about markup that is
+         * still unfinished is a small problem next to a frozen page.
+         */
+        setTimeout(once, 1000);
+        requestAnimationFrame(() => requestAnimationFrame(once));
+    };
+    if (typeof document !== "undefined" && document.readyState === "loading") {
+        document.addEventListener("DOMContentLoaded", afterTwoFrames, {
+            once: true,
+        });
+        return;
+    }
+    afterTwoFrames();
+}
+/**
+ * Waits until the element has been upgraded to its component, and returns it
+ * with the right type.
+ *
+ * The components with an imperative API have `show()`, `reportFailure()` and
+ * `extend()`. If one of them is called before `defineLt*` has run, the
+ * element is still a plain `HTMLElement`, and the call fails with
+ * "reportSuccess is not a function". In production it happened in the gap
+ * between the server's HTML being there and the registration being loaded:
+ * the first message from the event stream arrived in that gap, and the app
+ * put a `typeof` guard around every call to get around it.
+ *
+ * The helpers around the methods instead wait for `whenDefined` on the
+ * element's actual tag name, so a call that comes too early is made as soon
+ * as the registration is there. `upgrade()` covers an element not yet in the
+ * document; one that is in it is already upgraded when `whenDefined`
+ * resolves.
+ *
+ * An element nobody registers would otherwise wait silently for ever. After
+ * three seconds the helper says so in the console, once per tag name, and
+ * keeps waiting: if the registration comes late, the call should still be
+ * made.
+ */
+const UPGRADE_WARNING_MS = 3000;
+const warnedTags = new Set();
+export async function whenUpgraded(element) {
+    const tag = element.localName;
+    if (!customElements.get(tag)) {
+        const timer = setTimeout(() => {
+            if (customElements.get(tag) || warnedTags.has(tag))
+                return;
+            warnedTags.add(tag);
+            console.warn(`<${tag}> is not registered after ${UPGRADE_WARNING_MS / 1000} seconds. ` +
+                `Call defineLt() from @lo-tek/interfaces/register at startup, not in an effect.`, element);
+        }, UPGRADE_WARNING_MS);
+        // `finally`: `whenDefined` rejects a name without a hyphen, and without
+        // the cleanup the timer would have warned "not registered" three seconds
+        // after the call had already failed with the right error.
+        try {
+            await customElements.whenDefined(tag);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    customElements.upgrade(element);
+    return element;
+}
+//# sourceMappingURL=host-element.js.map

package/dist/components/host-element.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-element.js","sourceRoot":"","sources":["../../src/components/host-element.ts"],"names":[],"mappings":"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"}

package/dist/components/standalone/connection-status/connection-status.d.ts

@@ -0,0 +1,32 @@
+export declare const CONNECTION_STATUS_CLASS: "lt-connection-status";
+export declare const CONNECTION_STATUS_BAR_CLASS: "lt-connection-status__bar";
+export type ConnectionStatusOptions = {
+    /** The text when the connection is lost. */
+    offlineText?: string;
+    /** The text when it comes back. Shown for a short while. */
+    onlineText?: string;
+};
+export type ConnectionStatusAttributes = {
+    class: typeof CONNECTION_STATUS_CLASS;
+    role: "status";
+    "aria-live": "polite";
+    "offline-text"?: string;
+    "online-text"?: string;
+    "data-ignore-morph": "";
+};
+/**
+ * The attributes for the bar that says the connection is lost.
+ *
+ * By definition the server cannot tell you it is unreachable. When it is
+ * down, nothing comes from it to render. So the component creates all the
+ * content itself, and `data-ignore-morph` stops a later patch from tearing
+ * it away the moment the connection is back. The host is the live region,
+ * `role="status"` with `aria-live="polite"`, so the region exists before the
+ * bar and its text arrive.
+ *
+ * ```ts
+ * <lt-connection-status {...lt.connectionStatus()} />
+ * ```
+ */
+export declare const connectionStatus: ({ offlineText, onlineText, }?: ConnectionStatusOptions) => ConnectionStatusAttributes;
+//# sourceMappingURL=connection-status.d.ts.map

package/dist/components/standalone/connection-status/connection-status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection-status.d.ts","sourceRoot":"","sources":["../../../../src/components/standalone/connection-status/connection-status.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,uBAAuB,EAAG,sBAA+B,CAAA;AACtE,eAAO,MAAM,2BAA2B,EAAG,2BAAoC,CAAA;AAE/E,MAAM,MAAM,uBAAuB,GAAG;IACpC,4CAA4C;IAC5C,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,4DAA4D;IAC5D,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB,CAAA;AAED,MAAM,MAAM,0BAA0B,GAAG;IACvC,KAAK,EAAE,OAAO,uBAAuB,CAAA;IACrC,IAAI,EAAE,QAAQ,CAAA;IACd,WAAW,EAAE,QAAQ,CAAA;IACrB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,mBAAmB,EAAE,EAAE,CAAA;CACxB,CAAA;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,gBAAgB,GAAI,+BAG9B,uBAA4B,KAAG,0BAQ9B,CAAA"}

package/dist/components/standalone/connection-status/connection-status.js

@@ -0,0 +1,26 @@
+import { attributes } from "../../css/shared.js";
+export const CONNECTION_STATUS_CLASS = "lt-connection-status";
+export const CONNECTION_STATUS_BAR_CLASS = "lt-connection-status__bar";
+/**
+ * The attributes for the bar that says the connection is lost.
+ *
+ * By definition the server cannot tell you it is unreachable. When it is
+ * down, nothing comes from it to render. So the component creates all the
+ * content itself, and `data-ignore-morph` stops a later patch from tearing
+ * it away the moment the connection is back. The host is the live region,
+ * `role="status"` with `aria-live="polite"`, so the region exists before the
+ * bar and its text arrive.
+ *
+ * ```ts
+ * <lt-connection-status {...lt.connectionStatus()} />
+ * ```
+ */
+export const connectionStatus = ({ offlineText, onlineText, } = {}) => attributes({
+    class: CONNECTION_STATUS_CLASS,
+    role: "status",
+    "aria-live": "polite",
+    "offline-text": offlineText,
+    "online-text": onlineText,
+    "data-ignore-morph": "",
+});
+//# sourceMappingURL=connection-status.js.map

package/dist/components/standalone/connection-status/connection-status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection-status.js","sourceRoot":"","sources":["../../../../src/components/standalone/connection-status/connection-status.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAA;AAEhD,MAAM,CAAC,MAAM,uBAAuB,GAAG,sBAA+B,CAAA;AACtE,MAAM,CAAC,MAAM,2BAA2B,GAAG,2BAAoC,CAAA;AAkB/E;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,EAC/B,WAAW,EACX,UAAU,MACiB,EAAE,EAA8B,EAAE,CAC7D,UAAU,CAAC;IACT,KAAK,EAAE,uBAAuB;IAC9B,IAAI,EAAE,QAAiB;IACvB,WAAW,EAAE,QAAiB;IAC9B,cAAc,EAAE,WAAW;IAC3B,aAAa,EAAE,UAAU;IACzB,mBAAmB,EAAE,EAAW;CACjC,CAAC,CAAA"}

package/dist/components/standalone/connection-status/lt-connection-status.d.ts

@@ -0,0 +1,86 @@
+import { HostElement } from "../../host-element.js";
+export declare const LT_CONNECTION_STATUS_TAG: "lt-connection-status";
+/**
+ * Tells the user when the connection to the server is lost.
+ *
+ * By definition the server cannot tell you this. When it is unreachable,
+ * nothing comes from it. So this is a standalone component that creates all
+ * of its content itself.
+ *
+ * It is not decoration in an app that fetches content from the server as it
+ * goes. A page that loses its stream looks perfectly normal but is frozen,
+ * and a user filling in a form over a dead connection loses everything.
+ *
+ * `navigator.onLine` only says whether the machine has a network, not whether
+ * the server answers. That is why `reportFailure()` and `reportSuccess()`
+ * exist: the app calls them when a request fails or succeeds.
+ *
+ * ```ts
+ * const status = document.querySelector("lt-connection-status")
+ * try {
+ *   const response = await fetch("/api/save", { method: "POST", body })
+ *   if (!response.ok) throw new Error(response.statusText)
+ *   status.reportSuccess()
+ * } catch {
+ *   status.reportFailure()
+ * }
+ * ```
+ */
+export declare class LtConnectionStatus extends HostElement {
+    static observedAttributes: readonly ["offline-text", "online-text"];
+    private bar?;
+    private timer?;
+    /** True when the app has reported a failed request, regardless of navigator. */
+    private failing;
+    get offlineText(): string;
+    set offlineText(value: string);
+    get onlineText(): string;
+    set onlineText(value: string);
+    attributeChangedCallback(): void;
+    connectedCallback(): void;
+    private regionObserver?;
+    /**
+     * The region, as a pair and only when both are missing. A role the server
+     * wrote carries its own politeness (`alert` is assertive), and an
+     * `aria-live` added next to it would override that.
+     */
+    private markRegion;
+    disconnectedCallback(): void;
+    /**
+     * The bar, created empty first and filled afterwards.
+     *
+     * A live region must exist before its content arrives, or assistive
+     * technology does not announce the first change. The region is the host
+     * (see `connectedCallback`), so the bar is content inside a region that is
+     * already there; the text is still set in the next frame when the bar is
+     * new, so the bar and its text arrive as two changes.
+     *
+     * The bar is created only when it is needed, not on connection: when it
+     * was in the DOM before React hydrated, React found an element it had not
+     * rendered.
+     */
+    private ensureBar;
+    private write;
+    private showOffline;
+    private showOnline;
+    private scheduleRemoval;
+    private handleOffline;
+    private handleOnline;
+    private emit;
+    /** Reports that a request to the server failed. */
+    reportFailure(): void;
+    /** Reports that a request to the server succeeded again. */
+    reportSuccess(): void;
+}
+export declare function defineLtConnectionStatus(tagName?: string): void;
+/**
+ * `element.reportFailure()`, but waits for the registration first.
+ *
+ * This is where the gap showed up in production: the first message from the
+ * event stream came before `defineLtConnectionStatus()`, and the app got
+ * "reportSuccess is not a function". See `whenUpgraded`.
+ */
+export declare function reportFailure(element: Element): Promise<void>;
+/** `element.reportSuccess()`, but waits for the registration first. */
+export declare function reportSuccess(element: Element): Promise<void>;
+//# sourceMappingURL=lt-connection-status.d.ts.map

package/dist/components/standalone/connection-status/lt-connection-status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lt-connection-status.d.ts","sourceRoot":"","sources":["../../../../src/components/standalone/connection-status/lt-connection-status.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,WAAW,EAAgB,MAAM,uBAAuB,CAAA;AAMhF,eAAO,MAAM,wBAAwB,EAAG,sBAA+B,CAAA;AAUvE;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,kBAAmB,SAAQ,WAAW;IACjD,MAAM,CAAC,kBAAkB,2CAA2C;IAEpE,OAAO,CAAC,GAAG,CAAC,CAAa;IACzB,OAAO,CAAC,KAAK,CAAC,CAAQ;IACtB,gFAAgF;IAChF,OAAO,CAAC,OAAO,CAAQ;IAEvB,IAAI,WAAW,IAAI,MAAM,CAExB;IAED,IAAI,WAAW,CAAC,KAAK,EAAE,MAAM,EAE5B;IAED,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED,IAAI,UAAU,CAAC,KAAK,EAAE,MAAM,EAE3B;IAED,wBAAwB,IAAI,IAAI;IAWhC,iBAAiB,IAAI,IAAI;IAsCzB,OAAO,CAAC,cAAc,CAAC,CAAkB;IAEzC;;;;OAIG;IACH,OAAO,CAAC,UAAU;IAMlB,oBAAoB,IAAI,IAAI;IAS5B;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,SAAS;IAUjB,OAAO,CAAC,KAAK;IAuBb,OAAO,CAAC,WAAW;IAenB,OAAO,CAAC,UAAU;IAUlB,OAAO,CAAC,eAAe;IASvB,OAAO,CAAC,aAAa,CAEpB;IAED,OAAO,CAAC,YAAY,CAGnB;IAED,OAAO,CAAC,IAAI;IAIZ,mDAAmD;IACnD,aAAa,IAAI,IAAI;IAMrB,4DAA4D;IAC5D,aAAa,IAAI,IAAI;CAKtB;AAED,wBAAgB,wBAAwB,CACtC,OAAO,GAAE,MAAiC,GACzC,IAAI,CAEN;AAED;;;;;;GAMG;AACH,wBAAsB,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAGnE;AAED,uEAAuE;AACvE,wBAAsB,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAGnE"}