@lo-tek/interfaces 0.0.0 → 0.37.0

package/dist/components/frame/popover/popover.d.ts

@@ -0,0 +1,49 @@
+export declare const POPOVER_CLASS: "lt-popover";
+/** Which edge of the button the panel hangs from. `start` and `end` follow the reading direction. */
+export declare const popoverPlacements: readonly ["bottom-start", "bottom-end", "top-start", "top-end"];
+export type PopoverPlacement = (typeof popoverPlacements)[number];
+export declare function isPopoverPlacement(value: unknown): value is PopoverPlacement;
+export type PopoverOptions = {
+    /** Id of the panel. Connects the button to the panel with `aria-controls`. */
+    id: string;
+    /** The panel is open. Default: closed. */
+    open?: boolean;
+    /** Which edge the panel hangs from. Default: `bottom-start`. */
+    placement?: PopoverPlacement;
+};
+export type PopoverAttributes = {
+    host: {
+        open?: true;
+        placement?: PopoverPlacement;
+    };
+    trigger: {
+        type: "button";
+        "aria-expanded": "true" | "false";
+        "aria-controls": string;
+    };
+    panel: {
+        class: typeof POPOVER_CLASS;
+        id: string;
+        popover: "manual";
+    };
+};
+/**
+ * The attributes for a popover.
+ *
+ * The server writes both the button and the panel, with the wiring between
+ * them. `<lt-popover>` works out the position and closes on a click outside.
+ *
+ * ```ts
+ * const box = lt.popover({ id: "help" })
+ * ```
+ * ```html
+ * <lt-popover>
+ *   <button {...box.trigger}>What does this mean?</button>
+ *   <div {...box.panel}>We use the date of birth to find the right rate.</div>
+ * </lt-popover>
+ * ```
+ */
+export declare const popover: (({ id: givenId, open, placement, }: PopoverOptions) => PopoverAttributes) & {
+    isPlacement: typeof isPopoverPlacement;
+};
+//# sourceMappingURL=popover.d.ts.map

package/dist/components/frame/popover/popover.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"popover.d.ts","sourceRoot":"","sources":["../../../../src/components/frame/popover/popover.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,aAAa,EAAG,YAAqB,CAAA;AAElD,qGAAqG;AACrG,eAAO,MAAM,iBAAiB,iEAKpB,CAAA;AACV,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAA;AAEjE,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,gBAAgB,CAE5E;AAED,MAAM,MAAM,cAAc,GAAG;IAC3B,8EAA8E;IAC9E,EAAE,EAAE,MAAM,CAAA;IACV,0CAA0C;IAC1C,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,gEAAgE;IAChE,SAAS,CAAC,EAAE,gBAAgB,CAAA;CAC7B,CAAA;AAED,MAAM,MAAM,iBAAiB,GAAG;IAC9B,IAAI,EAAE;QACJ,IAAI,CAAC,EAAE,IAAI,CAAA;QACX,SAAS,CAAC,EAAE,gBAAgB,CAAA;KAC7B,CAAA;IACD,OAAO,EAAE;QACP,IAAI,EAAE,QAAQ,CAAA;QACd,eAAe,EAAE,MAAM,GAAG,OAAO,CAAA;QACjC,eAAe,EAAE,MAAM,CAAA;KACxB,CAAA;IACD,KAAK,EAAE;QACL,KAAK,EAAE,OAAO,aAAa,CAAA;QAC3B,EAAE,EAAE,MAAM,CAAA;QACV,OAAO,EAAE,QAAQ,CAAA;KAClB,CAAA;CACF,CAAA;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,OAAO,uCAKf,cAAc,KAAG,iBAAiB;;CAqCtC,CAAA"}

package/dist/components/frame/popover/popover.js

@@ -0,0 +1,64 @@
+import { attributes, idOrFallback } from "../../css/shared.js";
+export const POPOVER_CLASS = "lt-popover";
+/** Which edge of the button the panel hangs from. `start` and `end` follow the reading direction. */
+export const popoverPlacements = [
+    "bottom-start",
+    "bottom-end",
+    "top-start",
+    "top-end",
+];
+export function isPopoverPlacement(value) {
+    return popoverPlacements.includes(value);
+}
+/**
+ * The attributes for a popover.
+ *
+ * The server writes both the button and the panel, with the wiring between
+ * them. `<lt-popover>` works out the position and closes on a click outside.
+ *
+ * ```ts
+ * const box = lt.popover({ id: "help" })
+ * ```
+ * ```html
+ * <lt-popover>
+ *   <button {...box.trigger}>What does this mean?</button>
+ *   <div {...box.panel}>We use the date of birth to find the right rate.</div>
+ * </lt-popover>
+ * ```
+ */
+export const popover = Object.assign(({ id: givenId, open = false, placement = "bottom-start", }) => {
+    // The fallback only matters to someone without a type check.
+    const id = idOrFallback("lt.popover()", givenId);
+    return {
+        host: attributes({
+            // `open` must be on the host, not only in the button's aria-expanded.
+            // Without it the markup said the panel was open while the component
+            // thought it was closed. No preserve list: if a patch removes the
+            // attribute, the component puts it back, and `server-controlled` turns
+            // off the repair when the server is to decide the state.
+            open: open ? true : undefined,
+            placement: placement === "bottom-start" ? undefined : placement,
+        }),
+        trigger: attributes({
+            // A button without `type` submits the form it is in.
+            type: "button",
+            "aria-expanded": (open ? "true" : "false"),
+            "aria-controls": id,
+        }),
+        panel: attributes({
+            class: POPOVER_CLASS,
+            id,
+            // `manual` and not `auto`: the component closes the panel itself, so
+            // the button can close it again without the browser closing it first.
+            popover: "manual",
+        }),
+    };
+}, {
+    // The guard hangs on the function, as elsewhere in `lt`. The list sits
+    // next to it, as `popoverPlacements`, and not on the function: `placement`
+    // controls where JavaScript puts the panel, not CSS, and the guard for
+    // the classes requires every list on a builder function to do something
+    // in the CSS.
+    isPlacement: isPopoverPlacement,
+});
+//# sourceMappingURL=popover.js.map

package/dist/components/frame/popover/popover.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"popover.js","sourceRoot":"","sources":["../../../../src/components/frame/popover/popover.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAE9D,MAAM,CAAC,MAAM,aAAa,GAAG,YAAqB,CAAA;AAElD,qGAAqG;AACrG,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,cAAc;IACd,YAAY;IACZ,WAAW;IACX,SAAS;CACD,CAAA;AAGV,MAAM,UAAU,kBAAkB,CAAC,KAAc;IAC/C,OAAQ,iBAAwC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAA;AAClE,CAAC;AA4BD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,CAClC,CAAC,EACC,EAAE,EAAE,OAAO,EACX,IAAI,GAAG,KAAK,EACZ,SAAS,GAAG,cAAc,GACX,EAAqB,EAAE;IACtC,6DAA6D;IAC7D,MAAM,EAAE,GAAG,YAAY,CAAC,cAAc,EAAE,OAAO,CAAC,CAAA;IAEhD,OAAO;QACL,IAAI,EAAE,UAAU,CAAC;YACf,sEAAsE;YACtE,oEAAoE;YACpE,kEAAkE;YAClE,uEAAuE;YACvE,yDAAyD;YACzD,IAAI,EAAE,IAAI,CAAC,CAAC,CAAE,IAAc,CAAC,CAAC,CAAC,SAAS;YACxC,SAAS,EAAE,SAAS,KAAK,cAAc,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS;SAChE,CAAC;QACF,OAAO,EAAE,UAAU,CAAC;YAClB,qDAAqD;YACrD,IAAI,EAAE,QAAiB;YACvB,eAAe,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAqB;YAC9D,eAAe,EAAE,EAAE;SACpB,CAAC;QACF,KAAK,EAAE,UAAU,CAAC;YAChB,KAAK,EAAE,aAAa;YACpB,EAAE;YACF,qEAAqE;YACrE,sEAAsE;YACtE,OAAO,EAAE,QAAiB;SAC3B,CAAC;KACH,CAAA;AACH,CAAC,EACD;IACE,uEAAuE;IACvE,2EAA2E;IAC3E,uEAAuE;IACvE,wEAAwE;IACxE,cAAc;IACd,WAAW,EAAE,kBAAkB;CAChC,CACF,CAAA"}

package/dist/components/frame/session-timeout/lt-session-timeout.d.ts

@@ -0,0 +1,198 @@
+import { HostElement } from "../../host-element.js";
+export declare const LT_SESSION_TIMEOUT_TAG: "lt-session-timeout";
+/**
+ * The parts the warning finds, as selectors relative to the element. The
+ * component finds the parts with these, and the manifest describes them for
+ * whoever assembles the markup by hand, so the two cannot say different things.
+ */
+export declare const LT_SESSION_TIMEOUT_PARTS: {
+    readonly dialog: "dialog";
+    readonly title: "h1, h2, h3, h4, h5, h6";
+    readonly text: ".lt-session-timeout__text";
+    readonly count: ".lt-session-timeout__count";
+    readonly status: "[role='status']";
+    readonly button: "form[method=\"dialog\" i] button";
+};
+/**
+ * Warns before a signed-in session expires.
+ *
+ * This is the thing every large organisation builds itself and gets wrong.
+ * Either no warning comes, and the user loses a half-filled application
+ * form, or the dialog steals focus in the middle of a sentence, or the
+ * screen reader reads the countdown every second.
+ *
+ * The renderer writes the dialog and the text, so the warning is in the
+ * language the app uses, with the translation tool the app already has. The
+ * component keeps time: it counts activity, opens the dialog with
+ * `showModal()`, fills in the number and announces the countdown. That is all
+ * it writes, along with what a template may have forgotten: the class
+ * `lt-session-timeout__dialog` on the dialog, `role="alertdialog"`, and the
+ * name from the first heading, with an id on the heading when it lacks one.
+ *
+ * The parts are recognised by what must be there anyway: a `<dialog>` inside
+ * the host, `.lt-session-timeout__count` for the number, `[role=status]` for
+ * the announcement and the buttons in a `<form method="dialog">`. A button
+ * with `value="logout"` logs out. Every other way of closing the dialog,
+ * Escape and the button with `value="extend"` included, means "I am here",
+ * and extends the session.
+ *
+ * ```html
+ * <lt-session-timeout warn-at="1500" expires-at="1800" data-ignore-morph>
+ *   <dialog class="lt-session-timeout__dialog" role="alertdialog" aria-labelledby="session">
+ *     <h2 class="lt-session-timeout__title" id="session">You will soon be signed out</h2>
+ *     <p class="lt-session-timeout__text">
+ *       We will sign you out in <span class="lt-session-timeout__count" aria-hidden="true"></span>.
+ *     </p>
+ *     <span class="lt-sr-only" role="status"></span>
+ *     <form method="dialog" class="lt-session-timeout__actions">
+ *       <button class="lt-button" value="extend">Stay signed in</button>
+ *       <button class="lt-button" data-variant="secondary" value="logout">Sign out now</button>
+ *     </form>
+ *   </dialog>
+ * </lt-session-timeout>
+ * ```
+ *
+ * ```ts
+ * document.querySelector("lt-session-timeout")
+ *   .addEventListener("session-extend", () => fetch("/extend", { method: "POST" }))
+ * ```
+ */
+export declare class LtSessionTimeout extends HostElement {
+    static observedAttributes: readonly ["warn-at", "expires-at", "activity-interval"];
+    private ticker?;
+    private lastActivity;
+    /**
+     * When the component last sent `session-activity`, and whether the user has
+     * done anything since.
+     *
+     * The clock is reset by activity in the browser, but the server session does
+     * not know about it. A user typing in a long form without a single call to
+     * the server never got the warning, and the submission failed because the
+     * server session had expired. The event lets the app keep the server session
+     * alive. It is sent at the start of an interval, and at the end if the user
+     * has done something since, so the server is never more than one interval
+     * behind the clock here.
+     */
+    private lastActivityEvent;
+    private activitySinceEvent;
+    /** The seconds left at the previous tick, so a threshold is not skipped. */
+    private previousLeft?;
+    private previousFocus;
+    /**
+     * True from when the session expired, or the user chose to sign out, until
+     * `extend()` or `reset()` is called.
+     *
+     * Without this the cycle started again by itself, and an app that did not
+     * navigate away got a new dialog and a new `session-expired` every
+     * `expires-at` seconds, for a session that was already gone.
+     */
+    private expired;
+    /** The id the component gave the heading, so the same one comes back. */
+    private titleId?;
+    /**
+     * The dialog the component opened, until `close` has arrived.
+     *
+     * `close` arrives in a later task than the click that closed the dialog.
+     * When the clock ticked in between, `tick()` opened the dialog again and
+     * cleared `returnValue`, and the queued event then read `""` and extended
+     * the session: the user pressed "Sign out now", and the app got
+     * `session-extend`.
+     */
+    private shownDialog?;
+    /** Watches for `open` disappearing from a dialog in the top layer. See `repairOpen()`. */
+    private openObserver?;
+    /** Seconds without activity before the warning appears. */
+    get warnAt(): number;
+    set warnAt(value: number);
+    /** Seconds between each `session-activity` while the user is active. */
+    get activityInterval(): number;
+    set activityInterval(value: number);
+    /** Seconds without activity before the session expires. */
+    get expiresAt(): number;
+    set expiresAt(value: number);
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(): void;
+    /** The dialog the component controls: the first `<dialog>` inside the host. */
+    private get dialog();
+    private readSeconds;
+    /**
+     * Says so when markup and numbers do not add up, instead of staying quiet.
+     *
+     * `warn-at="1800" expires-at="1500"` gave `session-expired` without the
+     * dialog ever being shown, and a negative number gave a dialog on the first
+     * tick. The defaults are used when a number is not a number.
+     */
+    private validate;
+    /** The parts inside the dialog. Each of them makes the warning worse when missing. */
+    private validateParts;
+    /**
+     * Fills in what accessibility requires and a template may have forgotten:
+     * the role, and the name from the first heading. Only what is missing: a
+     * name from `aria-label` or `aria-labelledby` was written by the renderer,
+     * and stays.
+     */
+    private wire;
+    /**
+     * Puts `open` back on a dialog that is still in the top layer.
+     *
+     * `showModal()` sets the attribute itself, and the renderer did not send
+     * it. A morph without `data-ignore-morph` therefore removes it, and the
+     * dialog stayed in the top layer, invisible, with the rest of the page
+     * inert. The page was stuck. The number comes back on the next tick.
+     *
+     * The condition is `:modal` and not `open`: when the user closes the
+     * dialog, it leaves the top layer, and then the missing attribute is real.
+     * The same rule as in `<lt-dialog>`.
+     */
+    private repairOpen;
+    private registerActivity;
+    /**
+     * Sends `session-activity` when an interval has passed and the user was
+     * active.
+     *
+     * Not while the warning is showing or after the session has expired: then
+     * the app kept the server session alive while the clock here counted down
+     * towards `session-expired`. The interval is at least one second, or every
+     * scroll sent a call.
+     */
+    private reportActivity;
+    /**
+     * The user closed the dialog, or the component did.
+     *
+     * The component's own closes have their own reasons, and do nothing here.
+     * `value="logout"` logs out. Everything else, Escape and the button with
+     * `value="extend"` included, is "I am here". That also applies to a button
+     * with another value: otherwise the dialog closed, and the next tick opened
+     * it again a second later.
+     */
+    private handleClose;
+    private tick;
+    /** Writes the number, and the announcement when `announce` is true. */
+    private show;
+    private openDialog;
+    private closeDialog;
+    private emit;
+    /**
+     * Extends the session, closes the warning and sends `session-extend`.
+     *
+     * If the app listens for `session-extend` to ask the server to extend, it
+     * should call `reset()` when the answer comes, not this. Otherwise the
+     * answer sends a new `session-extend`, which sends a new call.
+     */
+    extend(): void;
+    /**
+     * Resets the clock without sending `session-extend`.
+     *
+     * For an app that has already extended the session itself, such as when an
+     * autosave went through. `extend()` would have asked the server a second
+     * time.
+     */
+    reset(): void;
+}
+export declare function defineLtSessionTimeout(tagName?: string): void;
+/** `element.extend()`, but waits for the registration first. See `whenUpgraded`. */
+export declare function extendSession(element: Element): Promise<void>;
+/** `element.reset()`, but waits for the registration first. See `whenUpgraded`. */
+export declare function resetSession(element: Element): Promise<void>;
+//# sourceMappingURL=lt-session-timeout.d.ts.map

package/dist/components/frame/session-timeout/lt-session-timeout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lt-session-timeout.d.ts","sourceRoot":"","sources":["../../../../src/components/frame/session-timeout/lt-session-timeout.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,WAAW,EAOZ,MAAM,uBAAuB,CAAA;AAS9B,eAAO,MAAM,sBAAsB,EAAG,oBAA6B,CAAA;AAEnE;;;;GAIG;AACH,eAAO,MAAM,wBAAwB;;;;;;;CAO3B,CAAA;AA0GV;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,qBAAa,gBAAiB,SAAQ,WAAW;IAC/C,MAAM,CAAC,kBAAkB,0DAIf;IAEV,OAAO,CAAC,MAAM,CAAC,CAAQ;IACvB,OAAO,CAAC,YAAY,CAAa;IACjC;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,iBAAiB,CAAI;IAC7B,OAAO,CAAC,kBAAkB,CAAQ;IAClC,4EAA4E;IAC5E,OAAO,CAAC,YAAY,CAAC,CAAQ;IAC7B,OAAO,CAAC,aAAa,CAA2B;IAChD;;;;;;;OAOG;IACH,OAAO,CAAC,OAAO,CAAQ;IACvB,yEAAyE;IACzE,OAAO,CAAC,OAAO,CAAC,CAAQ;IACxB;;;;;;;;OAQG;IACH,OAAO,CAAC,WAAW,CAAC,CAAmB;IACvC,0FAA0F;IAC1F,OAAO,CAAC,YAAY,CAAC,CAAkB;IAEvC,2DAA2D;IAC3D,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED,IAAI,MAAM,CAAC,KAAK,EAAE,MAAM,EAEvB;IAED,wEAAwE;IACxE,IAAI,gBAAgB,IAAI,MAAM,CAE7B;IAED,IAAI,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAEjC;IAED,2DAA2D;IAC3D,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,IAAI,SAAS,CAAC,KAAK,EAAE,MAAM,EAE1B;IAED,iBAAiB,IAAI,IAAI;IAmCzB,oBAAoB,IAAI,IAAI;IAe5B,wBAAwB,IAAI,IAAI;IAIhC,+EAA+E;IAC/E,OAAO,KAAK,MAAM,GAEjB;IAED,OAAO,CAAC,WAAW;IAKnB;;;;;;OAMG;IACH,OAAO,CAAC,QAAQ;IAqChB,sFAAsF;IACtF,OAAO,CAAC,aAAa;IAuBrB;;;;;OAKG;IACH,OAAO,CAAC,IAAI;IAkBZ;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,UAAU;IAMlB,OAAO,CAAC,gBAAgB,CAKvB;IAED;;;;;;;;OAQG;IACH,OAAO,CAAC,cAAc;IAmBtB;;;;;;;;OAQG;IACH,OAAO,CAAC,WAAW,CAqBlB;IAED,OAAO,CAAC,IAAI;IAiDZ,uEAAuE;IACvE,OAAO,CAAC,IAAI;IA4BZ,OAAO,CAAC,UAAU;IAiDlB,OAAO,CAAC,WAAW;IAMnB,OAAO,CAAC,IAAI;IAIZ;;;;;;OAMG;IACH,MAAM,IAAI,IAAI;IAKd;;;;;;OAMG;IACH,KAAK,IAAI,IAAI;CAKd;AAED,wBAAgB,sBAAsB,CACpC,OAAO,GAAE,MAA+B,GACvC,IAAI,CAEN;AAED,oFAAoF;AACpF,wBAAsB,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAGnE;AAED,mFAAmF;AACnF,wBAAsB,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAGlE"}