@mdbase-dev/ui 0.1.0-beta.126 → 0.1.0-beta.148

package/dist/collections/CollectionGate.js

@@ -0,0 +1,456 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useId, useLayoutEffect, useRef, useState } from "react";
+import { describeError } from "@mdbase-dev/sdk/describe";
+import { OpeningScreen } from "../screens.js";
+import { CollectionMdbaseContext } from "./CollectionSaveWarning.js";
+import { SwitcherContent } from "./CollectionSwitcher.js";
+import { RowDialogs, SignOutDialog } from "./dialogs.js";
+import { problemControl, actionNotice } from "./model.js";
+import { ActionButton, CollectionMark, GateFooter, ItemCopy, ItemMore, NoticeBlock, RowCopy, RowMore } from "./parts.js";
+import { SetupReview } from "./SetupReview.js";
+import { useAutoStart, useCollectionUi } from "./use-collection-ui.js";
+/**
+ * Everything before a collection is open: sign-in, choosing, approval, setup
+ * review and problems. In phase `ready` it renders the app, with a banner
+ * above it for a live problem (migrating, update required, access removed).
+ */
+export function CollectionGate({
+  children,
+  renderAppCollection,
+  extraActions,
+  layout = "page",
+  autoStart = true,
+  ...options
+}) {
+  const ui = useCollectionUi(options);
+  useAutoStart(options.mdbase, autoStart);
+  if (ui.appOpen && renderAppCollection) {
+    return _jsxs(CollectionMdbaseContext, {
+      value: options.mdbase,
+      children: [renderAppCollection(ui.appOpen.item, {
+        section: ui.appOpen.section,
+        chooseAnother: ui.actions.chooseAnother
+      }), _jsx(SignOutDialog, {
+        ui: ui
+      })]
+    });
+  }
+  if (ui.view.kind === "ready") {
+    return _jsxs(_Fragment, {
+      children: [ui.view.notice && _jsx("div", {
+        className: "mdbase-collections",
+        children: _jsx(NoticeBlock, {
+          notice: ui.view.notice,
+          ui: ui,
+          variant: "banner"
+        })
+      }), _jsx(CollectionMdbaseContext, {
+        value: options.mdbase,
+        children: children(ui.view.phase.connection)
+      }), _jsx(SignOutDialog, {
+        ui: ui
+      })]
+    });
+  }
+  return _jsx(GateScreen, {
+    ui: ui,
+    layout: layout,
+    extraActions: extraActions
+  });
+}
+/**
+ * For write-first apps and settings dialogs: the gate's screens in a panel and,
+ * once a collection is open, the switcher's list inline.
+ */
+export function CollectionPanel({
+  extraActions,
+  autoStart = true,
+  ...options
+}) {
+  const ui = useCollectionUi(options);
+  useAutoStart(options.mdbase, autoStart);
+  const [dialog, setDialog] = useState(null);
+  if (ui.view.kind !== "ready") return _jsx(GateScreen, {
+    ui: ui,
+    layout: "panel",
+    extraActions: extraActions
+  });
+  return _jsxs("div", {
+    className: "mdbase-collections mdbase-collections-panel",
+    children: [ui.view.notice && _jsx(NoticeBlock, {
+      notice: ui.view.notice,
+      ui: ui,
+      variant: "inline"
+    }), _jsx(SwitcherContent, {
+      ui: ui,
+      onDone: () => {},
+      onDialog: setDialog
+    }), _jsx(RowDialogs, {
+      ui: ui,
+      dialog: dialog,
+      onClose: () => setDialog(null)
+    }), _jsx(SignOutDialog, {
+      ui: ui
+    })]
+  });
+}
+/** One problem with its fix, for banners and toasts inside the app. Renders nothing when there is none. */
+export function CollectionProblem({
+  problem,
+  variant = "banner",
+  ...options
+}) {
+  const ui = useCollectionUi(options);
+  const {
+    view
+  } = ui;
+  let notice = view.kind === "ready" || view.kind === "problem" || view.kind === "unavailable" ? view.notice : null;
+  if (problem !== undefined) {
+    const described = describeError(problem);
+    const quiet = actionNotice(described);
+    notice = described && quiet ? {
+      ...quiet,
+      control: problemControl(described, {
+        collectionId: view.current?.id ?? null,
+        signedIn: view.signedIn,
+        open: view.kind === "ready"
+      })
+    } : null;
+  }
+  if (!notice) return null;
+  return _jsx("div", {
+    className: "mdbase-collections",
+    children: _jsx(NoticeBlock, {
+      notice: notice,
+      ui: ui,
+      variant: variant
+    })
+  });
+}
+function GateScreen({
+  ui,
+  layout,
+  extraActions
+}) {
+  const {
+    view,
+    options
+  } = ui;
+  const extra = typeof extraActions === "function" ? extraActions(view) : extraActions;
+  // An empty SDK list is not "no collections" when the app lists its own.
+  const appListed = view.kind === "choosing" && view.collections.length === 0 && (options.sections ?? []).some(section => section.items.length > 0);
+  const headingText = appListed ? ui.say("chooseHeading") : view.heading;
+  const lead = appListed ? null : view.lead;
+  const heading = useRef(null);
+  const root = useRef(null);
+  const [dialog, setDialog] = useState(null);
+  const previousKind = useRef(null);
+  // Move focus to the new heading when the phase changes, unless the person is busy elsewhere on the page.
+  useLayoutEffect(() => {
+    const before = previousKind.current;
+    previousKind.current = view.kind;
+    if (before === null || before === view.kind) return;
+    const active = document.activeElement;
+    if (!active || active === document.body || root.current?.contains(active)) heading.current?.focus({
+      preventScroll: true
+    });
+  }, [view.kind]);
+  const Heading = layout === "page" ? "h1" : "h2";
+  const opening = view.kind === "starting" || view.kind === "opening";
+  const announce = view.kind === "authorizing" ? view.heading : "";
+  return _jsxs("div", {
+    ref: root,
+    className: "mdbase-collections mdbase-collections-gate",
+    "data-layout": layout,
+    "data-phase": view.kind,
+    "aria-busy": ui.busy !== null || undefined,
+    children: [_jsxs("div", {
+      className: "mdbase-collections-gate-body",
+      children: [!opening && _jsxs("p", {
+        className: "mdbase-collections-brand",
+        children: [options.app.mark && _jsx("span", {
+          className: "mdbase-collections-brand-mark",
+          "aria-hidden": "true",
+          children: options.app.mark
+        }), _jsx("span", {
+          children: options.app.name
+        })]
+      }), _jsx(Heading, {
+        ref: heading,
+        tabIndex: -1,
+        className: opening ? "mdbase-collections-visually-hidden" : "mdbase-collections-heading",
+        children: headingText
+      }), opening ? _jsx(OpeningScreen, {
+        app: options.app,
+        layout: layout,
+        title: headingText,
+        detail: lead ?? undefined
+      }) : lead && _jsx("p", {
+        className: "mdbase-collections-lead",
+        children: lead
+      }), _jsx(GateBody, {
+        ui: ui,
+        extraActions: view.kind === "signed_out" ? extra : undefined,
+        onDialog: setDialog
+      }), ui.error && _jsx(NoticeBlock, {
+        notice: ui.error,
+        ui: ui,
+        variant: "inline"
+      }), _jsx(GateFooter, {
+        ui: ui,
+        chooseAnother: showsChooseAnother(view),
+        extra: view.kind === "signed_out" ? undefined : extra
+      })]
+    }), _jsx("p", {
+      className: "mdbase-collections-visually-hidden",
+      role: "status",
+      children: announce
+    }), _jsx(RowDialogs, {
+      ui: ui,
+      dialog: dialog,
+      onClose: () => setDialog(null)
+    }), _jsx(SignOutDialog, {
+      ui: ui
+    })]
+  });
+}
+function showsChooseAnother(view) {
+  if (!view.canChooseAnother) return false;
+  switch (view.kind) {
+    case "opening":
+      return view.slow;
+    case "needs_approval":
+    case "needs_setup":
+      return true;
+    case "problem":
+      return view.notice.control?.kind !== "choose_another";
+    default:
+      return false;
+  }
+}
+function GateBody({
+  ui,
+  extraActions,
+  onDialog
+}) {
+  const {
+    view,
+    copy,
+    busy,
+    actions
+  } = ui;
+  const inert = busy !== null;
+  switch (view.kind) {
+    case "starting":
+    case "opening":
+      return null;
+    case "signed_out":
+      return _jsxs(_Fragment, {
+        children: [view.notice && _jsx(NoticeBlock, {
+          notice: view.notice,
+          ui: ui,
+          variant: "inline"
+        }), _jsxs("div", {
+          className: "mdbase-collections-actions",
+          children: [_jsx(ActionButton, {
+            tone: "primary",
+            inert: inert,
+            progress: busy === "sign_out" ? copy.signingOut : busy === "sign_in" ? copy.addingCollection : null,
+            onClick: actions.signIn,
+            children: copy.signIn
+          }), extraActions]
+        }), _jsx(AppSections, {
+          ui: ui,
+          onDialog: onDialog
+        })]
+      });
+    case "authorizing":
+      return _jsxs("div", {
+        className: "mdbase-collections-actions",
+        children: [_jsx(ActionButton, {
+          tone: "secondary",
+          onClick: actions.reopen,
+          children: copy.openWindowAgain
+        }), busy === "sign_in" || busy === "add" || busy === "approve" ? _jsx(ActionButton, {
+          tone: "quiet",
+          onClick: actions.cancel,
+          children: copy.cancel
+        }) : null]
+      });
+    case "choosing":
+      return _jsxs(_Fragment, {
+        children: [view.notice && _jsx(NoticeBlock, {
+          notice: view.notice,
+          ui: ui,
+          variant: "inline"
+        }), view.collections.length > 0 && _jsx(CollectionList, {
+          ui: ui,
+          onDialog: onDialog
+        }), _jsx(AppSections, {
+          ui: ui,
+          onDialog: onDialog
+        }), _jsx("div", {
+          className: "mdbase-collections-actions",
+          children: _jsx(ActionButton, {
+            tone: view.collections.length > 0 ? "secondary" : "primary",
+            inert: inert,
+            progress: busy === "add" ? copy.addingCollection : null,
+            onClick: actions.addCollection,
+            children: copy.addCollection
+          })
+        })]
+      });
+    case "needs_approval":
+      return _jsx("div", {
+        className: "mdbase-collections-actions",
+        children: _jsx(ActionButton, {
+          tone: "primary",
+          inert: inert,
+          progress: busy === "approve" ? copy.addingCollection : null,
+          onClick: () => actions.approve(view.collectionId),
+          children: copy.reviewAccess
+        })
+      });
+    case "needs_setup":
+      return _jsx(SetupReview, {
+        ui: ui
+      }, view.collectionId);
+    case "problem":
+      return _jsx(NoticeBlock, {
+        notice: view.notice,
+        ui: ui
+      });
+    case "unavailable":
+    case "closed":
+      return _jsxs(_Fragment, {
+        children: [view.kind === "unavailable" && _jsx(NoticeBlock, {
+          notice: view.notice,
+          ui: ui
+        }), _jsx("div", {
+          className: "mdbase-collections-actions",
+          children: _jsx(ActionButton, {
+            tone: "primary",
+            onClick: () => globalThis.location?.reload(),
+            children: copy.reload
+          })
+        })]
+      });
+    case "ready":
+      return null;
+  }
+}
+/** The approved collections as a labelled list: one row per collection, never mixed with actions. */
+function CollectionList({
+  ui,
+  onDialog
+}) {
+  const id = useId();
+  const {
+    view,
+    copy,
+    busy,
+    actions
+  } = ui;
+  return _jsxs("section", {
+    className: "mdbase-collections-section",
+    "aria-labelledby": id,
+    children: [_jsx("h2", {
+      id: id,
+      className: "mdbase-collections-section-title",
+      children: copy.yourCollections
+    }), _jsx("ul", {
+      className: "mdbase-collections-list",
+      children: view.collections.map(row => {
+        const detailId = row.statusDetail ? `${id}-${row.id}` : undefined;
+        return _jsxs("li", {
+          className: "mdbase-collections-item",
+          children: [_jsxs("button", {
+            type: "button",
+            className: "mdbase-collections-row",
+            "aria-disabled": !row.available || busy !== null || undefined,
+            "aria-describedby": detailId,
+            onClick: () => {
+              if (row.available && busy === null) actions.select(row.id);
+            },
+            children: [_jsx(CollectionMark, {
+              row: row
+            }), _jsx(RowCopy, {
+              row: row,
+              ui: ui,
+              ...(detailId ? {
+                detailId
+              } : {})
+            })]
+          }), _jsx(RowMore, {
+            row: row,
+            ui: ui,
+            onDialog: onDialog
+          })]
+        }, row.id);
+      })
+    })]
+  });
+}
+/** The app's own sections ("Private collections"), after the SDK's list. */
+function AppSections({
+  ui,
+  onDialog
+}) {
+  const sections = (ui.options.sections ?? []).filter(section => section.items.length > 0 || section.empty);
+  if (sections.length === 0) return null;
+  return _jsx(_Fragment, {
+    children: sections.map(section => _jsx(AppSection, {
+      ui: ui,
+      section: section,
+      onDialog: onDialog
+    }, section.id))
+  });
+}
+function AppSection({
+  ui,
+  section,
+  onDialog
+}) {
+  const id = useId();
+  const {
+    busy,
+    actions
+  } = ui;
+  return _jsxs("section", {
+    className: "mdbase-collections-section",
+    "aria-labelledby": id,
+    "data-section": section.id,
+    children: [_jsx("h2", {
+      id: id,
+      className: "mdbase-collections-section-title",
+      children: section.title
+    }), section.items.length === 0 ? _jsx("p", {
+      className: "mdbase-collections-empty",
+      children: section.empty
+    }) : _jsx("ul", {
+      className: "mdbase-collections-list",
+      children: section.items.map(item => _jsxs("li", {
+        className: "mdbase-collections-item",
+        children: [_jsxs("button", {
+          type: "button",
+          className: "mdbase-collections-row",
+          "aria-disabled": item.disabled || busy !== null || undefined,
+          "aria-current": item.current || undefined,
+          onClick: () => {
+            if (busy === null) actions.selectItem(section, item);
+          },
+          children: [_jsx(CollectionMark, {
+            row: item
+          }), _jsx(ItemCopy, {
+            item: item,
+            ui: ui
+          })]
+        }), _jsx(ItemMore, {
+          item: item,
+          ui: ui,
+          onDialog: onDialog
+        })]
+      }, item.id))
+    })]
+  });
+}

package/dist/collections/CollectionSaveWarning.d.ts

@@ -0,0 +1,10 @@
+import type { Mdbase } from "@mdbase-dev/sdk";
+import { type JSX } from "react";
+/** The gate supplies the entry to status controls inside the open workspace. */
+export declare const CollectionMdbaseContext: import("react").Context<Mdbase | null>;
+/** Quiet storage-risk copy beside an app's save status. Never shown without
+ * the SDK's warning: persistence/installation policy stays SDK-owned. */
+export declare function useCollectionSaveWarning(supplied?: Mdbase): import("@mdbase-dev/sdk").MdbaseErrorDescription | null;
+export declare function CollectionSaveWarning({ mdbase }: {
+    readonly mdbase?: Mdbase;
+}): JSX.Element | null;

package/dist/collections/CollectionSaveWarning.js

@@ -0,0 +1,28 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { describeError } from "@mdbase-dev/sdk/describe";
+import { createContext, useContext, useSyncExternalStore } from "react";
+/** The gate supplies the entry to status controls inside the open workspace. */
+export const CollectionMdbaseContext = createContext(null);
+const emptySubscribe = () => () => {};
+const emptySnapshot = () => null;
+/** Quiet storage-risk copy beside an app's save status. Never shown without
+ * the SDK's warning: persistence/installation policy stays SDK-owned. */
+export function useCollectionSaveWarning(supplied) {
+  const inherited = useContext(CollectionMdbaseContext);
+  const mdbase = supplied ?? inherited;
+  const snapshot = useSyncExternalStore(mdbase?.subscribe ?? emptySubscribe, mdbase?.getSnapshot ?? emptySnapshot, emptySnapshot);
+  const warning = snapshot?.saveWarning;
+  return warning ? describeError(warning) : null;
+}
+export function CollectionSaveWarning({
+  mdbase
+}) {
+  const copy = useCollectionSaveWarning(mdbase);
+  if (!copy) return null;
+  return _jsx("span", {
+    className: "mdbase-collections-save-warning",
+    role: "status",
+    title: copy.message,
+    children: copy.message
+  });
+}

package/dist/collections/CollectionSwitcher.d.ts

@@ -0,0 +1,51 @@
+import { type JSX, type ReactNode, type RefObject } from "react";
+import { type RowDialog } from "./parts.js";
+import { type CollectionUi, type CollectionUiOptions } from "./use-collection-ui.js";
+export type CollectionSwitcherProps = CollectionUiOptions & {
+    readonly className?: string;
+    /**
+     * Leading content in the trigger: the app's icon, or "mark" for the open
+     * collection's initials. In the "icon" variant it replaces the folder glyph.
+     */
+    readonly icon?: ReactNode | "mark";
+    /**
+     * Whether the switcher is open. Leave it out and the switcher keeps its own
+     * state; pass it and the switcher only asks through `onOpenChange`.
+     */
+    readonly open?: boolean;
+    /** Called whenever the switcher opens or closes itself, controlled or not. */
+    readonly onOpenChange?: (open: boolean) => void;
+} & ({
+    /** "full": name and role; "compact": name only; "icon": a glyph for toolbars; "none": no trigger. */
+    readonly variant?: "full" | "compact" | "icon";
+    readonly anchorRef?: never;
+} | {
+    /**
+     * No trigger of its own: the app opens the switcher with `open` and
+     * `onOpenChange`, for instance from an item in its own menu.
+     */
+    readonly variant: "none";
+    /**
+     * The app's element the switcher belongs to, such as the button of the menu
+     * that offered it. The wide-screen popover is placed against it and focus
+     * returns to it on close. It must stay mounted while the switcher is open.
+     */
+    readonly anchorRef: RefObject<HTMLElement | null>;
+});
+/**
+ * The in-app collection switcher: a trigger that opens the approved collections
+ * (one click switches, no Connect window), "Add a collection…", "Manage access"
+ * and the account. A popover on wide screens, a bottom sheet on narrow ones.
+ *
+ * Pass `open` and `onOpenChange` to control it. With `variant="none"` it has no
+ * trigger, so an app can open it from its own control and pass that control's
+ * element (or the menu button that held it) as `anchorRef`.
+ */
+export declare function CollectionSwitcher({ variant, className, icon, open: openProp, onOpenChange, anchorRef, ...options }: CollectionSwitcherProps): JSX.Element;
+/** The switcher's list and actions, also shown inline by `CollectionPanel`. */
+export declare function SwitcherContent({ ui, onDone, onDialog }: {
+    readonly ui: CollectionUi;
+    readonly onDone: () => void;
+    /** Open a row's dialog (remove from list, delete), for an SDK collection or an app section item. */
+    readonly onDialog: (dialog: NonNullable<RowDialog>) => void;
+}): JSX.Element;