@mdbase-dev/ui 0.1.0-beta.125 → 0.1.0-beta.147

package/dist/mark-activity.js

@@ -1,9 +1,16 @@
 import { useEffect, useRef, useSyncExternalStore } from "react";
 /** Matches the signal animations in `motion.css`. */
-const SIGNAL_MS = { saved: 900, error: 1500 };
+const SIGNAL_MS = {
+  saved: 900,
+  error: 1500
+};
 /** Several notices often report the same save; one reaction is enough. */
 const REPEAT_MS = 400;
-const IDLE = { signal: null, progress: null, busy: null };
+const IDLE = {
+  signal: null,
+  progress: null,
+  busy: null
+};
 let snapshot = IDLE;
 let signal = null;
 let signalAt = 0;
@@ -13,109 +20,109 @@ const tasks = new Map();
 const holds = [];
 const listeners = new Set();
 function publish() {
-    const progress = tasks.size
-        ? [...tasks.values()].reduce((sum, fraction) => sum + fraction, 0) / tasks.size
-        : null;
-    snapshot = { signal, progress, busy: holds.at(-1)?.loop ?? null };
-    for (const listener of listeners)
-        listener();
+  const progress = tasks.size ? [...tasks.values()].reduce((sum, fraction) => sum + fraction, 0) / tasks.size : null;
+  snapshot = {
+    signal,
+    progress,
+    busy: holds.at(-1)?.loop ?? null
+  };
+  for (const listener of listeners) listener();
 }
 function clamp(fraction) {
-    return Number.isFinite(fraction) ? Math.min(1, Math.max(0, fraction)) : 0;
+  return Number.isFinite(fraction) ? Math.min(1, Math.max(0, fraction)) : 0;
 }
 /** Plays a one-shot reaction on the mark. A fresh error is never covered by a save. */
 export function signalMdbaseMark(kind) {
-    const now = Date.now();
-    if (signal && now - signalAt < REPEAT_MS && (signal.kind === kind || signal.kind === "error"))
-        return;
-    signal = { kind, id: nextId++ };
-    signalAt = now;
-    clearTimeout(signalTimer);
-    signalTimer = setTimeout(() => {
-        signal = null;
-        publish();
-    }, SIGNAL_MS[kind]);
+  const now = Date.now();
+  if (signal && now - signalAt < REPEAT_MS && (signal.kind === kind || signal.kind === "error")) return;
+  signal = {
+    kind,
+    id: nextId++
+  };
+  signalAt = now;
+  clearTimeout(signalTimer);
+  signalTimer = setTimeout(() => {
+    signal = null;
     publish();
+  }, SIGNAL_MS[kind]);
+  publish();
 }
 /** Shows an operation's known progress on the mark until it finishes, fails or is cancelled. */
 export function trackMdbaseMarkProgress(initial = 0) {
-    const id = nextId++;
-    tasks.set(id, clamp(initial));
+  const id = nextId++;
+  tasks.set(id, clamp(initial));
+  publish();
+  const end = kind => {
+    if (!tasks.delete(id)) return;
     publish();
-    const end = (kind) => {
-        if (!tasks.delete(id))
-            return;
-        publish();
-        if (kind)
-            signalMdbaseMark(kind);
-    };
-    return {
-        update(fraction) {
-            if (!tasks.has(id))
-                return;
-            tasks.set(id, clamp(fraction));
-            publish();
-        },
-        finish: () => end("saved"),
-        fail: () => end("error"),
-        cancel: () => end()
-    };
+    if (kind) signalMdbaseMark(kind);
+  };
+  return {
+    update(fraction) {
+      if (!tasks.has(id)) return;
+      tasks.set(id, clamp(fraction));
+      publish();
+    },
+    finish: () => end("saved"),
+    fail: () => end("error"),
+    cancel: () => end()
+  };
 }
 /** Loops the mark until the returned release is called. Releasing twice is harmless. */
 export function holdMdbaseMarkBusy(loop) {
-    const id = nextId++;
-    holds.push({ id, loop });
+  const id = nextId++;
+  holds.push({
+    id,
+    loop
+  });
+  publish();
+  return () => {
+    const index = holds.findIndex(hold => hold.id === id);
+    if (index < 0) return;
+    holds.splice(index, 1);
     publish();
-    return () => {
-        const index = holds.findIndex((hold) => hold.id === id);
-        if (index < 0)
-            return;
-        holds.splice(index, 1);
-        publish();
-    };
+  };
 }
 function subscribe(listener) {
-    listeners.add(listener);
-    return () => listeners.delete(listener);
+  listeners.add(listener);
+  return () => listeners.delete(listener);
 }
 export function getMdbaseMarkActivity() {
-    return snapshot;
+  return snapshot;
 }
 export function useMdbaseMarkActivity() {
-    return useSyncExternalStore(subscribe, getMdbaseMarkActivity, () => IDLE);
+  return useSyncExternalStore(subscribe, getMdbaseMarkActivity, () => IDLE);
 }
 /**
  * Shows `fraction` on the mark while it is a number. Becoming null or unmounting ends the
  * operation quietly; call `signalMdbaseMark` separately if the end deserves a reaction.
  */
 export function useMdbaseMarkProgress(fraction) {
-    const handle = useRef(null);
-    const tracking = typeof fraction === "number";
-    useEffect(() => {
-        if (!tracking)
-            return;
-        const progress = trackMdbaseMarkProgress();
-        handle.current = progress;
-        return () => {
-            progress.cancel();
-            handle.current = null;
-        };
-    }, [tracking]);
-    useEffect(() => {
-        if (typeof fraction === "number")
-            handle.current?.update(fraction);
-    }, [fraction]);
+  const handle = useRef(null);
+  const tracking = typeof fraction === "number";
+  useEffect(() => {
+    if (!tracking) return;
+    const progress = trackMdbaseMarkProgress();
+    handle.current = progress;
+    return () => {
+      progress.cancel();
+      handle.current = null;
+    };
+  }, [tracking]);
+  useEffect(() => {
+    if (typeof fraction === "number") handle.current?.update(fraction);
+  }, [fraction]);
 }
 /** Loops the mark while `loop` is set. */
 export function useMdbaseMarkBusy(loop) {
-    useEffect(() => (loop ? holdMdbaseMarkBusy(loop) : undefined), [loop]);
+  useEffect(() => loop ? holdMdbaseMarkBusy(loop) : undefined, [loop]);
 }
 /** For tests: forget every signal, operation and hold. */
 export function resetMdbaseMarkActivity() {
-    clearTimeout(signalTimer);
-    signal = null;
-    signalAt = 0;
-    tasks.clear();
-    holds.length = 0;
-    publish();
+  clearTimeout(signalTimer);
+  signal = null;
+  signalAt = 0;
+  tasks.clear();
+  holds.length = 0;
+  publish();
 }

package/dist/permission-selection.js

@@ -1,21 +1,31 @@
 import { useEffect, useState } from "react";
 /** A permission review survives polling, but never silently rebases onto changed access. */
 export function usePermissionSelection(id, allowed) {
-    const key = JSON.stringify([id, [...allowed].sort()]);
-    const [review, setReview] = useState(() => ({ key, selected: [...allowed], needsReview: false }));
-    const changedExternally = review.key !== key;
-    const needsReview = changedExternally && JSON.stringify([id, [...review.selected].sort()]) !== key;
-    useEffect(() => {
-        if (changedExternally)
-            setReview({ key, selected: [...allowed], needsReview });
-    }, [key, changedExternally, needsReview]);
-    return {
-        selected: changedExternally ? [...allowed] : review.selected,
-        needsReview: changedExternally ? needsReview : review.needsReview,
-        setSelected: (selected) => setReview((current) => ({
-            ...current,
-            selected: typeof selected === "function" ? selected(current.selected) : selected
-        })),
-        acknowledge: () => setReview((current) => ({ ...current, needsReview: false }))
-    };
+  const key = JSON.stringify([id, [...allowed].sort()]);
+  const [review, setReview] = useState(() => ({
+    key,
+    selected: [...allowed],
+    needsReview: false
+  }));
+  const changedExternally = review.key !== key;
+  const needsReview = changedExternally && JSON.stringify([id, [...review.selected].sort()]) !== key;
+  useEffect(() => {
+    if (changedExternally) setReview({
+      key,
+      selected: [...allowed],
+      needsReview
+    });
+  }, [key, changedExternally, needsReview]);
+  return {
+    selected: changedExternally ? [...allowed] : review.selected,
+    needsReview: changedExternally ? needsReview : review.needsReview,
+    setSelected: selected => setReview(current => ({
+      ...current,
+      selected: typeof selected === "function" ? selected(current.selected) : selected
+    })),
+    acknowledge: () => setReview(current => ({
+      ...current,
+      needsReview: false
+    }))
+  };
 }

package/dist/popover.js

@@ -3,160 +3,168 @@ import { useEffect, useEffectEvent, useLayoutEffect } from "react";
  * Where a popover opens beside its trigger: below when it fits, otherwise on whichever side
  * has more room, lined up with the trigger's start (or end) edge and kept inside the viewport.
  */
-export function anchoredPlacement(trigger, popover, viewport, { gap = 4, margin = 8, align = "start" } = {}) {
-    const below = viewport.height - trigger.bottom - gap - margin;
-    const above = trigger.top - gap - margin;
-    const opensUp = popover.height > below && above > below;
-    const room = Math.max(120, opensUp ? above : below);
-    const height = Math.min(popover.height, room);
-    const width = Math.max(popover.width, trigger.width);
-    const start = align === "end" ? trigger.left + trigger.width - width : trigger.left;
-    return {
-        top: opensUp ? trigger.top - gap - height : trigger.bottom + gap,
-        left: Math.max(margin, Math.min(start, viewport.width - width - margin)),
-        maxHeight: room
-    };
+export function anchoredPlacement(trigger, popover, viewport, {
+  gap = 4,
+  margin = 8,
+  align = "start"
+} = {}) {
+  const below = viewport.height - trigger.bottom - gap - margin;
+  const above = trigger.top - gap - margin;
+  const opensUp = popover.height > below && above > below;
+  const room = Math.max(120, opensUp ? above : below);
+  const height = Math.min(popover.height, room);
+  const width = Math.max(popover.width, trigger.width);
+  const start = align === "end" ? trigger.left + trigger.width - width : trigger.left;
+  return {
+    top: opensUp ? trigger.top - gap - height : trigger.bottom + gap,
+    left: Math.max(margin, Math.min(start, viewport.width - width - margin)),
+    maxHeight: room
+  };
 }
 function place(trigger, popover, options) {
-    const box = trigger.getBoundingClientRect();
-    if (options.matchWidth)
-        popover.style.minWidth = `${box.width}px`;
-    popover.style.maxHeight = "";
-    const placement = anchoredPlacement(box, { width: popover.offsetWidth, height: popover.scrollHeight }, { width: window.innerWidth, height: window.innerHeight }, options);
-    popover.style.top = `${placement.top}px`;
-    popover.style.left = `${placement.left}px`;
-    popover.style.maxHeight = `${placement.maxHeight}px`;
+  const box = trigger.getBoundingClientRect();
+  if (options.matchWidth) popover.style.minWidth = `${box.width}px`;
+  popover.style.maxHeight = "";
+  const placement = anchoredPlacement(box, {
+    width: popover.offsetWidth,
+    height: popover.scrollHeight
+  }, {
+    width: window.innerWidth,
+    height: window.innerHeight
+  }, options);
+  popover.style.top = `${placement.top}px`;
+  popover.style.left = `${placement.left}px`;
+  popover.style.maxHeight = `${placement.maxHeight}px`;
 }
 // Browsers without the Popover API (and jsdom) keep the element in place instead.
 function showInTopLayer(element) {
-    if (typeof element.showPopover === "function")
-        element.showPopover();
+  if (typeof element.showPopover === "function") element.showPopover();
 }
 function hideFromTopLayer(element) {
-    if (typeof element.hidePopover === "function" && element.matches(":popover-open"))
-        element.hidePopover();
+  if (typeof element.hidePopover === "function" && element.matches(":popover-open")) element.hidePopover();
 }
 function onScreen(element) {
-    const box = element.getBoundingClientRect();
-    return box.width > 0 && box.bottom > 0 && box.top < window.innerHeight
-        && box.right > 0 && box.left < window.innerWidth;
+  const box = element.getBoundingClientRect();
+  return box.width > 0 && box.bottom > 0 && box.top < window.innerHeight && box.right > 0 && box.left < window.innerWidth;
 }
 /**
  * Shows a select's list in the top layer beside its trigger, focuses it, and dismisses it when
  * the pointer lands elsewhere or the page scrolls or resizes underneath it.
  */
 export function useSelectPopover(open, triggerRef, listRef, onDismiss) {
-    const dismiss = useEffectEvent(onDismiss);
-    useLayoutEffect(() => {
-        const list = listRef.current;
-        const trigger = triggerRef.current;
-        if (!open || !list || !trigger)
-            return undefined;
-        showInTopLayer(list);
-        place(trigger, list, { matchWidth: true });
-        list.focus({ preventScroll: true });
-        return () => {
-            hideFromTopLayer(list);
-        };
-    }, [open, triggerRef, listRef]);
-    useEffect(() => {
-        const list = listRef.current;
-        const trigger = triggerRef.current;
-        if (!open || !list || !trigger)
-            return undefined;
-        const outside = (event) => {
-            const target = event.target;
-            if (target && !list.contains(target) && !trigger.contains(target))
-                dismiss();
-        };
-        // Content under the list can move (a panel scrolls, a list re-renders): the list follows
-        // its trigger, and closes only once the trigger has left the screen.
-        const follow = (event) => {
-            if (list.contains(event.target))
-                return;
-            if (onScreen(trigger))
-                place(trigger, list, { matchWidth: true });
-            else
-                dismiss();
-        };
-        const onResize = () => dismiss();
-        document.addEventListener("pointerdown", outside, true);
-        document.addEventListener("scroll", follow, true);
-        window.addEventListener("resize", onResize);
-        return () => {
-            document.removeEventListener("pointerdown", outside, true);
-            document.removeEventListener("scroll", follow, true);
-            window.removeEventListener("resize", onResize);
-        };
-    }, [open, triggerRef, listRef]);
+  const dismiss = useEffectEvent(onDismiss);
+  useLayoutEffect(() => {
+    const list = listRef.current;
+    const trigger = triggerRef.current;
+    if (!open || !list || !trigger) return undefined;
+    showInTopLayer(list);
+    place(trigger, list, {
+      matchWidth: true
+    });
+    list.focus({
+      preventScroll: true
+    });
+    return () => {
+      hideFromTopLayer(list);
+    };
+  }, [open, triggerRef, listRef]);
+  useEffect(() => {
+    const list = listRef.current;
+    const trigger = triggerRef.current;
+    if (!open || !list || !trigger) return undefined;
+    const outside = event => {
+      const target = event.target;
+      if (target && !list.contains(target) && !trigger.contains(target)) dismiss();
+    };
+    // Content under the list can move (a panel scrolls, a list re-renders): the list follows
+    // its trigger, and closes only once the trigger has left the screen.
+    const follow = event => {
+      if (list.contains(event.target)) return;
+      if (onScreen(trigger)) place(trigger, list, {
+        matchWidth: true
+      });else dismiss();
+    };
+    const onResize = () => dismiss();
+    document.addEventListener("pointerdown", outside, true);
+    document.addEventListener("scroll", follow, true);
+    window.addEventListener("resize", onResize);
+    return () => {
+      document.removeEventListener("pointerdown", outside, true);
+      document.removeEventListener("scroll", follow, true);
+      window.removeEventListener("resize", onResize);
+    };
+  }, [open, triggerRef, listRef]);
 }
 /**
  * Keeps a mounted menu in the top layer beside its trigger. It closes on an outside press,
  * Escape (returning focus to the trigger), Tab or a resize.
  */
-export function useMenuPopover(menuRef, triggerRef, onClose, { width, align = "start", focus = '[aria-checked="true"], [role^="menuitem"]', busy = false }) {
-    const close = useEffectEvent(onClose);
-    const locked = useEffectEvent(() => busy);
-    useLayoutEffect(() => {
-        const menu = menuRef.current;
-        const trigger = triggerRef.current;
-        if (!menu || !trigger)
-            return undefined;
-        showInTopLayer(menu);
-        if (width !== undefined)
-            menu.style.width = `${Math.min(width, window.innerWidth - 16)}px`;
-        place(trigger, menu, { gap: 6, align, matchWidth: false });
-        (menu.querySelector(focus) ?? menu).focus({ preventScroll: true });
-        return () => {
-            hideFromTopLayer(menu);
-        };
-    }, [menuRef, triggerRef, width, align, focus]);
-    useEffect(() => {
-        const onPointerDown = (event) => {
-            const target = event.target;
-            if (target && !locked() && !menuRef.current?.contains(target) && !triggerRef.current?.contains(target)) {
-                close(false);
-            }
-        };
-        const onKeyDown = (event) => {
-            if ((event.key === "Escape" || event.key === "Tab") && !locked()) {
-                if (event.key === "Escape") {
-                    event.preventDefault();
-                    event.stopPropagation();
-                }
-                close(event.key === "Escape");
-            }
-        };
-        const onResize = () => close(false);
-        document.addEventListener("pointerdown", onPointerDown, true);
-        document.addEventListener("keydown", onKeyDown, true);
-        window.addEventListener("resize", onResize);
-        return () => {
-            document.removeEventListener("pointerdown", onPointerDown, true);
-            document.removeEventListener("keydown", onKeyDown, true);
-            window.removeEventListener("resize", onResize);
-        };
-    }, [menuRef, triggerRef]);
+export function useMenuPopover(menuRef, triggerRef, onClose, {
+  width,
+  align = "start",
+  focus = '[aria-checked="true"], [role^="menuitem"]',
+  busy = false
+}) {
+  const close = useEffectEvent(onClose);
+  const locked = useEffectEvent(() => busy);
+  useLayoutEffect(() => {
+    const menu = menuRef.current;
+    const trigger = triggerRef.current;
+    if (!menu || !trigger) return undefined;
+    showInTopLayer(menu);
+    if (width !== undefined) menu.style.width = `${Math.min(width, window.innerWidth - 16)}px`;
+    place(trigger, menu, {
+      gap: 6,
+      align,
+      matchWidth: false
+    });
+    (menu.querySelector(focus) ?? menu).focus({
+      preventScroll: true
+    });
+    return () => {
+      hideFromTopLayer(menu);
+    };
+  }, [menuRef, triggerRef, width, align, focus]);
+  useEffect(() => {
+    const onPointerDown = event => {
+      const target = event.target;
+      if (target && !locked() && !menuRef.current?.contains(target) && !triggerRef.current?.contains(target)) {
+        close(false);
+      }
+    };
+    const onKeyDown = event => {
+      if ((event.key === "Escape" || event.key === "Tab") && !locked()) {
+        if (event.key === "Escape") {
+          event.preventDefault();
+          event.stopPropagation();
+        }
+        close(event.key === "Escape");
+      }
+    };
+    const onResize = () => close(false);
+    document.addEventListener("pointerdown", onPointerDown, true);
+    document.addEventListener("keydown", onKeyDown, true);
+    window.addEventListener("resize", onResize);
+    return () => {
+      document.removeEventListener("pointerdown", onPointerDown, true);
+      document.removeEventListener("keydown", onKeyDown, true);
+      window.removeEventListener("resize", onResize);
+    };
+  }, [menuRef, triggerRef]);
 }
 /**
  * Arrow keys, Home and End move between a menu's enabled items. From a text field inside the
  * menu (a filter), Home and End stay in the field and the arrows enter the list.
  */
 export function moveMenuFocus(event, menu) {
-    if (!menu || !["ArrowDown", "ArrowUp", "Home", "End"].includes(event.key))
-        return;
-    const items = [...menu.querySelectorAll('[role^="menuitem"]:not(:disabled)')];
-    const inField = document.activeElement instanceof HTMLInputElement && menu.contains(document.activeElement);
-    if (inField && (event.key === "Home" || event.key === "End"))
-        return;
-    event.preventDefault();
-    const current = items.indexOf(document.activeElement);
-    const next = event.key === "Home"
-        ? 0
-        : event.key === "End"
-            ? items.length - 1
-            : inField
-                ? 0
-                : (current + (event.key === "ArrowDown" ? 1 : -1) + items.length) % items.length;
-    items[next]?.focus({ preventScroll: true });
+  if (!menu || !["ArrowDown", "ArrowUp", "Home", "End"].includes(event.key)) return;
+  const items = [...menu.querySelectorAll('[role^="menuitem"]:not(:disabled)')];
+  const inField = document.activeElement instanceof HTMLInputElement && menu.contains(document.activeElement);
+  if (inField && (event.key === "Home" || event.key === "End")) return;
+  event.preventDefault();
+  const current = items.indexOf(document.activeElement);
+  const next = event.key === "Home" ? 0 : event.key === "End" ? items.length - 1 : inField ? 0 : (current + (event.key === "ArrowDown" ? 1 : -1) + items.length) % items.length;
+  items[next]?.focus({
+    preventScroll: true
+  });
 }

package/dist/screens.d.ts

@@ -1,16 +1,27 @@
-import type { JSX, ReactNode } from "react";
+import { type JSX, type ReactNode } from "react";
 import type { MdbaseAppId } from "./apps.js";
 /**
  * What an app shows while it opens a collection: its wordmark, scanning, and a quiet line
  * saying what it is waiting for. A failure keeps the same place, shakes the mark once and
  * offers a retry.
+ *
+ * With `entrance="flock"` it is the launch screen: a 42px mark that the flock flies onto
+ * from the edges of the screen, once per page, before it starts scanning. Pair it with
+ * `useLaunchEntrancePlaying()` so a fast open does not cut the entrance off.
  */
-export declare function OpeningScreen({ app, title, detail, error, onRetry }: {
-    readonly app: MdbaseAppId;
+export declare function OpeningScreen(props: {
+    /** A built-in app wordmark, or the name of an independent collection app. */
+    readonly app: MdbaseAppId | {
+        readonly name: string;
+        readonly mark?: ReactNode;
+    };
+    /** Embedded gates must not add a second main landmark. */
+    readonly layout?: "page" | "panel" | undefined;
     readonly title: string;
     readonly detail?: string | undefined;
     readonly error?: string | null | undefined;
     readonly onRetry?: (() => void) | undefined;
+    readonly entrance?: "flock" | undefined;
 }): JSX.Element;
 /**
  * The screen before a collection is open: the app's wordmark, a headline, what the app will
@@ -28,3 +39,9 @@ export declare function ConnectLayout({ app, title, lead, status, error, detail,
     readonly footnote?: ReactNode | undefined;
     readonly children?: ReactNode | undefined;
 }): JSX.Element;
+/**
+ * True while the launch entrance is flying. An app that opens quickly keeps its
+ * opening screen until this is false, so the entrance is never cut off mid-flight;
+ * it lasts at most two seconds.
+ */
+export declare function useLaunchEntrancePlaying(): boolean;