@pathscale/ui 3.0.0 → 3.2.0

package/dist/layouts.manifest.json

@@ -1,7 +1,7 @@
 {
   "format": "solid-layouts-library-v2",
   "package": "@pathscale/ui",
-  "version": "3.0.0",
+  "version": "3.2.0",
   "components": {
     "Accordion": {
       "kind": "embedded"
@@ -153,6 +153,9 @@
     "Composer": {
       "kind": "embedded"
     },
+    "ConnectionSettings": {
+      "kind": "embedded"
+    },
     "CookieConsent": {
       "kind": "embedded"
     },

package/dist/lib/focus.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Keyboard focus, for the overlays that have to contain it.
+ *
+ * Here rather than in a component's own module because two components had
+ * their own copy of the same twenty lines -- Drawer's in `Drawer.a11y.ts` and
+ * Dialog's written out inline -- and the overlay manager now needs it too. A
+ * `lib` importing from a `components` directory to reach one of those copies
+ * would be the layering inverted to avoid moving a helper.
+ */
+/** Everything inside `container` a person can Tab to, in document order. */
+export declare const getFocusable: (container: HTMLElement) => HTMLElement[];
+/** Move focus to the first thing inside `container` that will take it. */
+export declare const focusFirst: (container: HTMLElement) => void;
+/**
+ * Keep Tab inside a scope, wrapping at both ends.
+ *
+ * The scope is a list, not one element, because a modal's content is not
+ * always one subtree: a Popover opened from inside a Dialog portals its
+ * content elsewhere in the document, and it is still part of what the person
+ * is looking at. Trapping in the Dialog's element alone would make the popover
+ * unreachable by keyboard; treating the popover as the scope would let Tab
+ * leave the modal behind it. Both belong.
+ *
+ * Order matters: the containers are given innermost-last, and the focusables
+ * are concatenated in that order, so tabbing off the end of the newest overlay
+ * wraps to the start of the modal that owns the scope.
+ *
+ * A scope with nothing focusable in it takes focus itself, so Tab cannot
+ * escape a modal that is still loading its content.
+ */
+export declare const trapFocus: (event: KeyboardEvent, scope: HTMLElement | HTMLElement[]) => void;

package/dist/lib/focus.js

@@ -0,0 +1,39 @@
+const FOCUSABLE_SELECTOR = "a[href],area[href],button:not([disabled]),input:not([disabled]):not([type='hidden']),select:not([disabled]),textarea:not([disabled]),[contenteditable='true'],[tabindex]:not([tabindex='-1'])";
+const getFocusable = (container)=>Array.from(container.querySelectorAll(FOCUSABLE_SELECTOR)).filter((el)=>!el.hidden && el.tabIndex >= 0 && "true" !== el.getAttribute("aria-hidden"));
+const focusFirst = (container)=>{
+    const autofocus = container.querySelector("[autofocus]");
+    if (autofocus) return void autofocus.focus();
+    const nodes = getFocusable(container);
+    if (nodes.length > 0) return void nodes[0].focus();
+    container.focus();
+};
+const trapFocus = (event, scope)=>{
+    const containers = Array.isArray(scope) ? scope : [
+        scope
+    ];
+    const container = containers[0];
+    if (!container) return;
+    const nodes = containers.flatMap((element)=>getFocusable(element));
+    if (0 === nodes.length) {
+        event.preventDefault();
+        container.focus();
+        return;
+    }
+    const first = nodes[0];
+    const last = nodes[nodes.length - 1];
+    const active = document.activeElement;
+    if (!event.shiftKey && active === last) {
+        event.preventDefault();
+        first.focus();
+        return;
+    }
+    if (event.shiftKey && (active === first || containers.some((element)=>active === element))) {
+        event.preventDefault();
+        last.focus();
+    }
+    if (active && !containers.some((element)=>element.contains(active))) {
+        event.preventDefault();
+        (event.shiftKey ? last : first).focus();
+    }
+};
+export { focusFirst, getFocusable, trapFocus };

package/dist/lib/overlay.d.ts

@@ -0,0 +1,94 @@
+/**
+ * One owner for the things overlapping overlays have to agree about.
+ *
+ * Dialog, Drawer and Popover each had their own copy of this, which is fine
+ * until two of them are open at once, and then it is not:
+ *
+ * - **Escape closed every layer.** Each component bound its own `keydown` on
+ *   `document`, and every listener that saw the key acted on it. Opening a
+ *   Popover from inside a Dialog and pressing Escape dismissed both, because
+ *   nothing established which overlay owned the event.
+ *
+ * - **The body could be left unscrollable for good.** Dialog and Drawer had
+ *   *separate* module-scope lock counters, each saving `document.body.style
+ *   .overflow` the first time it locked. Dialog opens and saves `""`. Drawer
+ *   opens and saves `"hidden"` -- Dialog's value, not the page's. Dialog closes
+ *   and restores `""`. Drawer closes and restores `"hidden"`. The page is now
+ *   stuck, and nothing on screen says why.
+ *
+ * Components supply policy -- whether they are dismissable, what closing means
+ * -- and this owns the mechanism.
+ */
+type DismissReason = "escape";
+interface OverlayEntry {
+    dismiss: (reason: DismissReason) => void;
+    /** Asked at dismiss time, not at registration: `closeOnEscape` can change. */
+    dismissable: () => boolean;
+    /**
+     * This overlay's own content, asked at key time because it is portalled and
+     * mounts after registration.
+     *
+     * Declared by modal and non-modal overlays alike. A Popover is not modal and
+     * still has to be part of the focus scope of whatever it was opened from, or
+     * Tab cannot reach it.
+     */
+    element?: () => HTMLElement | undefined;
+    /**
+     * Whether this overlay contains focus while it is open.
+     *
+     * True for Dialog and Drawer, false for Popover. It decides who *owns* the
+     * scope; `element` decides what is *in* it.
+     *
+     * Here rather than on each component for the same reason `dismiss` is.
+     * Dialog and Drawer each bound their own document-level Tab listener and
+     * each gated it on "am I visible", so with both open both traps ran and the
+     * one behind could pull focus out of the one in front. Which overlay owns
+     * the keyboard is a question about all of them.
+     */
+    modal?: boolean;
+}
+/**
+ * The elements Tab may move within, given what is open.
+ *
+ * The innermost *modal* owns the scope, and everything opened above it is
+ * inside that scope. Empty when nothing open contains focus, which is Tab
+ * belonging to the page.
+ *
+ * Asking only the top entry was wrong in the one arrangement this manager
+ * exists for: a Popover opened from inside a Dialog is the top entry and is
+ * not modal, so Tab did nothing at all and focus walked out to the page behind
+ * a dialog that was still open -- worse than before the manager, where the
+ * Dialog's own listener at least still ran. Trapping in the modal's element
+ * alone is the opposite failure: the popover's portalled content sits outside
+ * that element and Tab could never reach it.
+ *
+ * Exported for tests. This repository has no DOM in its unit tests -- the
+ * harness is the DOM-level instrument -- and the bugs here are arrangements
+ * rather than components, which is exactly what a one-component-per-page sweep
+ * cannot set up. Keeping the decision pure is what makes it assertable at all.
+ */
+export declare const focusScope: (entries: readonly OverlayEntry[]) => HTMLElement[];
+/**
+ * Claim the keyboard while an overlay is open.
+ *
+ * Call this **when the overlay becomes visible**, not when the component
+ * mounts, and call the returned function when it closes. The stack is the
+ * order overlays opened in, and it can only be that if registration is.
+ *
+ * The most recently registered overlay owns Escape, and — when it declares
+ * `trapFocusIn` — Tab.
+ */
+export declare const registerOverlay: (entry: OverlayEntry) => (() => void);
+/** How many overlays currently own dismissal. Exposed for tests. */
+export declare const overlayDepth: () => number;
+/**
+ * Hold the body still while an overlay is open.
+ *
+ * One counter for the whole library. The saved values are captured on the
+ * first lock and restored on the last release, so overlapping overlays cannot
+ * save each other's `hidden` and restore it afterwards.
+ */
+export declare const lockBodyScroll: () => (() => void);
+/** Outstanding scroll locks. Exposed for tests. */
+export declare const bodyScrollLockDepth: () => number;
+export {};

package/dist/lib/overlay.js

@@ -0,0 +1,72 @@
+import { trapFocus } from "./focus.js";
+const stack = [];
+let keydownBound = false;
+const overlay_top = ()=>stack[stack.length - 1];
+const focusScope = (entries)=>{
+    for(let i = entries.length - 1; i >= 0; i -= 1)if (entries[i]?.modal) return entries.slice(i).map((entry)=>entry.element?.()).filter((element)=>Boolean(element));
+    return [];
+};
+const handleKeyDown = (event)=>{
+    if (event.defaultPrevented) return;
+    const entry = overlay_top();
+    if (!entry) return;
+    if ("Tab" === event.key) {
+        const scope = focusScope(stack);
+        if (scope.length > 0) trapFocus(event, scope);
+        return;
+    }
+    if ("Escape" !== event.key) return;
+    if (!entry.dismissable()) return;
+    event.preventDefault();
+    entry.dismiss("escape");
+};
+const bindKeyDown = ()=>{
+    if (keydownBound || "u" < typeof document) return;
+    document.addEventListener("keydown", handleKeyDown);
+    keydownBound = true;
+};
+const unbindKeyDown = ()=>{
+    if (!keydownBound || stack.length > 0 || "u" < typeof document) return;
+    document.removeEventListener("keydown", handleKeyDown);
+    keydownBound = false;
+};
+const registerOverlay = (entry)=>{
+    stack.push(entry);
+    bindKeyDown();
+    let released = false;
+    return ()=>{
+        if (released) return;
+        released = true;
+        const index = stack.lastIndexOf(entry);
+        if (-1 !== index) stack.splice(index, 1);
+        unbindKeyDown();
+    };
+};
+const overlayDepth = ()=>stack.length;
+let lockCount = 0;
+let restoreOverflow = "";
+let restorePaddingRight = "";
+const lockBodyScroll = ()=>{
+    if ("u" < typeof document) return ()=>{};
+    if (0 === lockCount) {
+        restoreOverflow = document.body.style.overflow;
+        restorePaddingRight = document.body.style.paddingRight;
+        const scrollbarWidth = window.innerWidth - document.documentElement.clientWidth;
+        if (scrollbarWidth > 0) document.body.style.paddingRight = `${scrollbarWidth}px`;
+        document.body.style.overflow = "hidden";
+    }
+    lockCount += 1;
+    let released = false;
+    return ()=>{
+        if (released) return;
+        released = true;
+        if (lockCount <= 0) return;
+        lockCount -= 1;
+        if (0 === lockCount) {
+            document.body.style.overflow = restoreOverflow;
+            document.body.style.paddingRight = restorePaddingRight;
+        }
+    };
+};
+const bodyScrollLockDepth = ()=>lockCount;
+export { bodyScrollLockDepth, focusScope, lockBodyScroll, overlayDepth, registerOverlay };