npm - staffa - Versions diffs - 0.18.1 → 0.18.3 - Mend

staffa 0.18.1 → 0.18.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (20) hide show

package/dist/components/autocomplete.d.ts +4 -0
package/dist/components/autocomplete.js +83 -35
package/dist/components/main.js +9 -7
package/dist/components/menu.js +8 -11
package/dist/components/panels.d.ts +22 -5
package/dist/components/panels.js +169 -66
package/dist/components/tooltip.js +8 -10
package/dist/core.d.ts +13 -0
package/dist/core.js +38 -0
package/dist/staffa.esm.js +1 -1
package/dist/theme.js +22 -6
package/package.json +1 -1
package/skill/autocomplete.md +4 -0
package/src/components/autocomplete.ts +102 -38
package/src/components/main.ts +9 -7
package/src/components/menu.ts +8 -11
package/src/components/panels.ts +171 -66
package/src/components/tooltip.ts +9 -11
package/src/core.ts +33 -0
package/src/theme.ts +22 -7

package/dist/components/autocomplete.d.ts CHANGED Viewed

@@ -31,6 +31,10 @@ export interface AutocompleteOptions extends FieldOptions {
  * optional free-text entry, and full keyboard control (arrows, enter, escape,
  * backspace-to-remove). Implements the ARIA combobox/listbox pattern.
  *
+ * The suggestion list is portalled to `document.body`, so a dialog or a
+ * scrolling column can neither clip it nor grow a scrollbar around it. It hangs
+ * off whichever side of the field has the room, and follows it as things move.
+ *
  * @example
  * ```ts
  * // Single select from a fixed list

package/dist/components/autocomplete.js CHANGED Viewed

@@ -1,9 +1,8 @@
 import A from "aberdeen";
-import { uniqueId } from "../core.js";
+import { followAnchor, mountPortal, uniqueId } from "../core.js";
 import { drawField } from "./field.js";
 A.insertGlobalCss({
     ".s-ac": {
-        "&": "position:relative",
         // Same light inset field as `.s-input` (see field.ts), derived from the surface.
         "> .s-control": "display:flex flex-wrap:wrap align-items:center gap:$1 background: color-mix(in oklab, $s-bg, $s-text 4%); color:$s-text border: 1px solid $s-faint; r:$s-radius padding: 0.3em 0.4em; cursor:text; transition: border-color 0.15s, box-shadow 0.15s;",
         "> .s-control:hover": "border-color: color-mix(in oklab, $s-text, $s-bg 55%);",
@@ -13,16 +12,56 @@ A.insertGlobalCss({
         ".s-chip > button": "cursor:pointer border:0 background:transparent fg:$s-muted font-size:1.1em line-height:1 padding: 0 0.2em; r:4px",
         ".s-chip > button:hover": "fg:$s-text background:$s-faint",
         "input": "flex:1 min-width:6ch border:0 background:transparent color:inherit outline:none padding:0.25em",
-        // Background, border, radius and elevation come from the popup's
-        // `.s-s.neutral.shadow` surface (see below).
-        "> .s-menu": "position:absolute top:100% left:0 right:0 z-index:20 margin-top:4px max-height:15rem overflow-y:auto list-style:none p:$1 margin-bottom:0",
-        "> .s-menu li": "margin:0",
+    },
+    // Background, border, radius and elevation come from the `.s-s.neutral.shadow`
+    // surface it carries; `place()` below sizes and positions it. Both of its
+    // classes are named here: standing in `<body>` rather than inside the field,
+    // it would otherwise lose to theme.ts's flow margins on `ul` and `li`.
+    ".s-ac-menu.s-s": {
+        "&": "position:fixed max-height:15rem overflow-y:auto list-style:none p:$1 margin:0",
+        li: "margin:0",
         ".s-option": "padding: 0.45em 0.6em; r:6px cursor:pointer transition: background 0.1s;",
         ".s-option[aria-selected=true]": "background: color-mix(in srgb, $s-text 10%, transparent);",
         ".s-add": "fg:$s-accent font-style:italic",
         ".s-empty": "padding: 0.45em 0.6em; fg:$s-muted",
     },
 });
+// Only one list is up at a time — it belongs to whichever field has focus — so
+// one portal at the end of <body> serves them all. Drawn inside the field, the
+// list would be clipped by a dialog or a scrolling column, and would stretch
+// that scroller's bar to reach it.
+const $popup = A.proxy({ cur: null });
+/** Hang the list under the field — or over it, when that's where the room is. */
+function place(el, r) {
+    const gap = 4, edge = 8;
+    // Measured at the stylesheet's own cap, so the flip is decided on the height
+    // the list wants, not on whatever the last placement clamped it to.
+    el.style.maxHeight = "";
+    const want = el.offsetHeight;
+    const below = window.innerHeight - r.bottom - gap - edge;
+    const above = r.top - gap - edge;
+    const up = want > below && above > below;
+    el.style.left = `${r.left}px`;
+    el.style.width = `${r.width}px`;
+    el.style.maxHeight = `${Math.min(want, Math.max(up ? above : below, 60))}px`;
+    el.style.top = up ? "auto" : `${r.bottom + gap}px`;
+    el.style.bottom = up ? `${window.innerHeight - r.top + gap}px` : "auto";
+}
+mountPortal(() => {
+    const p = $popup.cur;
+    if (!p)
+        return;
+    let sizeChanged;
+    const el = A("ul.s-ac-menu.s-s.neutral.shadow role=listbox", `id=${p.id} z-index:${p.zIndex}`, () => {
+        // A press in the list must not blur the field: the click that follows is
+        // what commits, and dragging the scrollbar has to keep it open too.
+        A("mousedown=", (e) => e.preventDefault());
+        p.draw();
+        // Re-run as you type, with the rows; the list's height changes with them.
+        sizeChanged?.();
+    });
+    sizeChanged = followAnchor(p.anchor, (r) => place(el, r));
+});
 function normOption(o) {
     return typeof o === "string" ? { value: o, label: o } : { value: o.value, label: o.label ?? o.value };
 }
@@ -31,6 +70,10 @@ function normOption(o) {
  * optional free-text entry, and full keyboard control (arrows, enter, escape,
  * backspace-to-remove). Implements the ARIA combobox/listbox pattern.
  *
+ * The suggestion list is portalled to `document.body`, so a dialog or a
+ * scrolling column can neither clip it nor grow a scrollbar around it. It hangs
+ * off whichever side of the field has the room, and follows it as things move.
+ *
  * @example
  * ```ts
  * // Single select from a fixed list
@@ -103,11 +146,36 @@ export function autocomplete(opts) {
         const arr = opts.bind.value ?? [];
         opts.bind.value = arr.filter((v) => v !== value);
     };
+    let inputEl;
+    /** The list's rows. Runs in the body portal, on this field's state. */
+    const drawList = () => {
+        const list = filtered();
+        const q = $st.query.trim();
+        const showAdd = opts.allowCustom !== false && q !== "" && !list.some((o) => o.label.toLowerCase() === q.toLowerCase());
+        list.forEach((option, i) => {
+            A("li.s-option role=option", `id=${menuId}-opt-${i}`, () => {
+                A(() => A("aria-selected=", $st.active === i ? "true" : "false"));
+                A("#", option.label);
+                A("click=", () => commit(option.value, inputEl));
+                A("mousemove=", () => {
+                    $st.active = i;
+                });
+            });
+        });
+        if (showAdd) {
+            A("li.s-option.s-add role=option", () => {
+                A("#", `Add "${q}"`);
+                A("click=", () => commit(q, inputEl));
+            });
+        }
+        if (list.length === 0 && !showAdd) {
+            A("li.s-empty #No matches");
+        }
+    };
     drawField(opts, (id, isInvalid) => {
         A("div.s-ac", opts.inputAttrs, () => {
             A(() => A("aria-invalid=", isInvalid() ? "true" : "false"));
-            let inputEl;
-            A("div.s-control", () => {
+            const controlEl = A("div.s-control", () => {
                 A("click=", () => inputEl?.focus());
                 // Chips for multi-select.
                 A(() => {
@@ -156,36 +224,16 @@ export function autocomplete(opts) {
                     A("keydown=", (e) => onKey(e, inputEl));
                 });
             });
-            // The suggestions popup.
+            // Hand the list to the portal for as long as it is up. Its layer clears
+            // the dialog the field sits in, but stays under one that may open over
+            // it — a field on the page can't paint across a modal.
             A(() => {
                 if (!$st.open)
                     return;
-                const list = filtered();
-                const q = $st.query.trim();
-                const showAdd = opts.allowCustom !== false && q !== "" && !list.some((o) => o.label.toLowerCase() === q.toLowerCase());
-                A("ul.s-menu.s-s.neutral.shadow role=listbox", `id=${menuId}`, () => {
-                    list.forEach((option, i) => {
-                        A("li.s-option role=option", `id=${menuId}-opt-${i}`, () => {
-                            A(() => A("aria-selected=", $st.active === i ? "true" : "false"));
-                            A("#", option.label);
-                            A("mousedown=", (e) => e.preventDefault());
-                            A("click=", () => commit(option.value, inputEl));
-                            A("mousemove=", () => {
-                                $st.active = i;
-                            });
-                        });
-                    });
-                    if (showAdd) {
-                        A("li.s-option.s-add role=option", () => {
-                            A("#", `Add "${q}"`);
-                            A("mousedown=", (e) => e.preventDefault());
-                            A("click=", () => commit(q, inputEl));
-                        });
-                    }
-                    if (list.length === 0 && !showAdd) {
-                        A("li.s-empty #No matches");
-                    }
-                });
+                const zIndex = controlEl.closest(".s-dialog") ? 350 : 150;
+                $popup.cur = { id: menuId, anchor: controlEl, zIndex, draw: drawList };
+                A.clean(() => { if ($popup.cur?.id === menuId)
+                    $popup.cur = null; });
             });
             // Hidden inputs so the selection participates in native FormData.
             A(() => {

package/dist/components/main.js CHANGED Viewed

@@ -7,7 +7,7 @@ import { drawMenu, isFloatingMenuOpen, consumeBranchNav, anyCurrent, registerMen
 import { menu as menuIcon, x as closeIcon } from "../icons.js";
 import { iconButton } from "./button.js";
 import { isDialogOpen } from "./dialog.js";
-import { PanelStackController, SMALL_MAX_PX } from "./panels.js";
+import { PAGE_MS, PanelStackController, SMALL_MAX_PX } from "./panels.js";
 /** The default nav column, hairline included — see {@link MainOptions.navWidth}. */
 const NAV_W = 200;
 A.insertGlobalCss({
@@ -66,7 +66,7 @@ A.insertGlobalCss({
         // — past the viewport edge. The transition is dormant except for the
         // incoming half of the nav-panel hand-off (see `slideContentIn`).
         ".s-body main": "flex:1 min-width:0 min-height:0 overflow-x:hidden overflow-y:auto display:flex flex-direction:column " +
-            "transition: transform var(--s-panel-ms) ease;",
+            `transition: transform ${PAGE_MS}ms ease;`,
         // A one-shot starting position: parked one screen to the right, with the
         // transition off so it snaps there. Removing the class animates it home.
         ".s-body main.s-slide-in": "transform: translateX(100%); transition:none",
@@ -95,14 +95,16 @@ A.insertGlobalCss({
         // Under the sticky header's 10: they never overlap, but the bar should win.
         "position:absolute inset:0 z-index:5 display:flex flex-direction:column " +
             "overflow-y:auto overscroll-behavior:contain border:0 r:0 padding:$2 gap:$1 " +
-            "transition: transform var(--s-panel-ms) ease, visibility 0s;",
+            `transition: transform ${PAGE_MS}ms ease, visibility 0s;`,
         // Parked one screen left: what the `create=`/`destroy=` hooks transition out
         // of and back into. On dismissal (this rule's transition) `visibility` flips
-        // only at the slide's end, so the dismissed page isn't reachable while it
-        // waits for Aberdeen's removal timer; on entry it flips instantly (the `0s`
-        // above), or the opening page would refuse the focus handed to it mid-slide.
+        // only at the slide's end — a delayed zero-length transition, whose constant
+        // start value costs nothing per frame — so the dismissed page isn't
+        // reachable while it waits for Aberdeen's removal timer; on entry it flips
+        // instantly (the `0s` above), or the opening page would refuse the focus
+        // handed to it mid-slide.
         "&.s-nav-page-off": "transform:translateX(-100%) pointer-events:none visibility:hidden " +
-            "transition: transform var(--s-panel-ms) ease, visibility var(--s-panel-ms);",
+            `transition: transform ${PAGE_MS}ms ease, visibility 0s ${PAGE_MS}ms;`,
         // Roomier than the dropdown's: every row here is a thumb target.
         ".s-menu-item": "padding: $2 $3; min-height:3rem font-size:1.05em gap:$3",
     },

package/dist/components/menu.js CHANGED Viewed

@@ -1,6 +1,6 @@
 import A from "aberdeen";
 import { matchCurrent, current as currentRoute, go } from "aberdeen/route";
-import { drawSlot, mountPortal, focusFirst } from "../core.js";
+import { drawSlot, followAnchor, mountPortal, focusFirst } from "../core.js";
 import { menu as menuIcon, chevronRight, externalLink as newTabIcon, link as linkIcon } from "../icons.js";
 import { button } from "./button.js";
 import { toast } from "./toast.js";
@@ -551,17 +551,14 @@ mountPortal(() => {
         document.removeEventListener("click", onClick, true);
         document.removeEventListener("keydown", onKey, true);
     });
-    // Position after layout, then focus the first enabled item.
+    // At the supplied point when given — the pointer location for a context menu
+    // — otherwise below the anchor.
+    followAnchor(f.at ? new DOMRect(f.at.x, f.at.y, 0, 0) : f.anchor, (rect) => positionMenu(menuEl, rect));
+    // Once it can take focus: the current-page item if there is one, else the
+    // first focusable element (covers custom slot content, not just `.s-menu-item`s).
     requestAnimationFrame(() => {
-        if (!document.body.contains(menuEl))
-            return;
-        // Position at the supplied point (a zero-size rect) when given — e.g. the
-        // pointer location for a context menu — otherwise below the anchor.
-        const rect = f.at ? { left: f.at.x, right: f.at.x, top: f.at.y, bottom: f.at.y } : f.anchor.getBoundingClientRect();
-        positionMenu(menuEl, rect);
-        // Focus the current-page item if there is one, else the first focusable
-        // element (covers custom slot content, not just `.s-menu-item`s).
-        focusFirst(menuEl, ".s-menu-item[aria-current=page]");
+        if (document.body.contains(menuEl))
+            focusFirst(menuEl, ".s-menu-item[aria-current=page]");
     });
 });
 // ─── Public API ──────────────────────────────────────────────────────────────

package/dist/components/panels.d.ts CHANGED Viewed

@@ -287,6 +287,13 @@ export interface Panel<P = Record<string, string | number | string[]>> {
      */
     open(href: string, how?: "push" | "replace" | "open"): Promise<boolean>;
 }
+/**
+ * The one duration every bit of shell motion shares: the enter/exit fades, the
+ * slides, the narrow-screen nav slide. Interpolated into every transition as a
+ * literal — the shared constant is what keeps CSS and JS in step — and also
+ * published as the `--s-panel-ms` custom property for app CSS.
+ */
+export declare const PAGE_MS = 250;
 export declare const SMALL_MAX_PX = 540;
 /** Options the stack needs from its shell. */
 export interface PanelStackOptions {
@@ -453,6 +460,8 @@ export declare class PanelStackController implements PanelStack {
     private lastGeom?;
     private layoutQueued;
     private timers;
+    /** Elements playing their exit fade, each riding its anchor's motion (see `layout`). */
+    private exiting;
     /** The arrangement the navigation in flight is heading for; see {@link intended}. */
     private intent;
     /** The navigation the router hasn't settled yet, if any. */
@@ -530,13 +539,21 @@ export declare class PanelStackController implements PanelStack {
      */
     private beginClose;
     /**
-     * A closed panel's send-off, run by Aberdeen once its scope is gone: it fades
-     * where it stands, inert, and leaves the DOM on `transitionend`. A fixed timer
-     * would race the transition and pull the element a frame early, making the
-     * panel appear to fade half-way and vanish; the timeout is only a fallback for
-     * when no `transitionend` is coming (transitions off, element never placed).
+     * A closed panel's send-off, run by Aberdeen once its scope is gone: it fades,
+     * inert, riding its anchor's slide (see `layout`), and leaves the DOM once
+     * the fade is over (see {@link afterFade}).
      */
     private playExit;
+    /**
+     * Run `done` once `el`'s transition of `prop` is over. The real signal is
+     * `transitionend` — or `transitioncancel`, for one a resize snaps short —
+     * so the transition's actual length rules, however long: DevTools' slowed
+     * animations stretch it tenfold without touching any timer. The timer only
+     * stands in for a transition that never starts at all (transitions off,
+     * element never placed, nothing to travel), which is why one proving real
+     * (`transitionrun`) disarms it.
+     */
+    private afterTransition;
     /**
      * The arrangement navigation works from: the one we're on the way to while a
      * change is still settling, the one on screen otherwise. That window is common