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

package/dist/collections/dialogs.d.ts

@@ -0,0 +1,27 @@
+import { type JSX } from "react";
+import type { CollectionRow } from "./model.js";
+import { type RowDialog } from "./parts.js";
+import type { CollectionUi, DeleteCollectionOutcome } from "./use-collection-ui.js";
+type Target = Pick<CollectionRow, "id" | "name">;
+/** Hide a collection on this device. Nothing is deleted and access stays. */
+export declare function ForgetCollectionDialog({ ui, collection, onClose }: {
+    readonly ui: CollectionUi;
+    readonly collection: Target;
+    readonly onClose: () => void;
+}): JSX.Element;
+/** Owner only: type the name to delete a collection for everyone. The SDK and server check both again. */
+export declare function DeleteCollectionDialog({ ui, collection, onClose }: {
+    readonly ui: CollectionUi;
+    readonly collection: Target;
+    readonly onClose: (outcome: DeleteCollectionOutcome) => void;
+}): JSX.Element;
+/** Sign-out found changes that haven't reached mdbase: wait, or sign out and lose them here. */
+export declare function SignOutDialog({ ui }: {
+    readonly ui: CollectionUi;
+}): JSX.Element | null;
+export declare function RowDialogs({ ui, dialog, onClose }: {
+    readonly ui: CollectionUi;
+    readonly dialog: RowDialog;
+    readonly onClose: () => void;
+}): JSX.Element | null;
+export {};

package/dist/collections/dialogs.js

@@ -0,0 +1,169 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { describeError } from "@mdbase-dev/sdk/describe";
+import { useId, useState } from "react";
+import { ActionButton, CollectionDialog } from "./parts.js";
+/** Hide a collection on this device. Nothing is deleted and access stays. */
+export function ForgetCollectionDialog({
+  ui,
+  collection,
+  onClose
+}) {
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState(null);
+  const forget = () => {
+    setBusy(true);
+    setError(null);
+    ui.options.mdbase.forget(collection.id).then(onClose, cause => {
+      setBusy(false);
+      setError(describeError(cause)?.message ?? null);
+    });
+  };
+  return _jsxs(CollectionDialog, {
+    title: ui.say("forgetTitle", {
+      collection: collection.name
+    }),
+    busy: busy,
+    onClose: onClose,
+    footer: _jsxs(_Fragment, {
+      children: [_jsx(ActionButton, {
+        tone: "quiet",
+        inert: busy,
+        onClick: onClose,
+        children: ui.copy.cancel
+      }), _jsx(ActionButton, {
+        tone: "primary",
+        progress: busy ? ui.copy.forgetConfirm : null,
+        onClick: forget,
+        children: ui.copy.forgetConfirm
+      })]
+    }),
+    children: [_jsx("p", {
+      children: ui.say("forgetBody")
+    }), error && _jsx("p", {
+      className: "mdbase-collections-dialog-error",
+      role: "alert",
+      children: error
+    })]
+  });
+}
+/** Owner only: type the name to delete a collection for everyone. The SDK and server check both again. */
+export function DeleteCollectionDialog({
+  ui,
+  collection,
+  onClose
+}) {
+  const id = useId();
+  const [typed, setTyped] = useState("");
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState(null);
+  const [failed, setFailed] = useState(false);
+  const matches = typed.trim() === collection.name.trim();
+  const dismiss = () => onClose(failed ? "failed" : "cancelled");
+  const remove = () => {
+    if (!matches || busy) return;
+    setBusy(true);
+    setError(null);
+    ui.options.mdbase.deleteCollection(collection.id, {
+      confirmName: typed
+    }).then(() => onClose("deleted"), cause => {
+      setBusy(false);
+      setFailed(true);
+      setError(describeError(cause)?.message ?? null);
+    });
+  };
+  return _jsxs(CollectionDialog, {
+    alert: true,
+    title: ui.say("deleteTitle", {
+      collection: collection.name
+    }),
+    busy: busy,
+    onClose: dismiss,
+    footer: _jsxs(_Fragment, {
+      children: [_jsx(ActionButton, {
+        tone: "quiet",
+        inert: busy,
+        onClick: dismiss,
+        children: ui.copy.cancel
+      }), _jsx(ActionButton, {
+        tone: "danger",
+        inert: !matches,
+        progress: busy ? ui.copy.deleting : null,
+        onClick: remove,
+        children: ui.copy.deleteConfirm
+      })]
+    }),
+    children: [_jsx("p", {
+      children: ui.copy.deleteBody
+    }), _jsxs("form", {
+      onSubmit: event => {
+        event.preventDefault();
+        remove();
+      },
+      children: [_jsx("label", {
+        className: "mdbase-collections-field-label",
+        htmlFor: id,
+        children: ui.say("deleteTypeName", {
+          collection: collection.name
+        })
+      }), _jsx("input", {
+        id: id,
+        className: "mdbase-collections-field",
+        value: typed,
+        autoComplete: "off",
+        spellCheck: false,
+        disabled: busy,
+        onChange: event => setTyped(event.target.value),
+        "data-autofocus": true
+      })]
+    }), error && _jsx("p", {
+      className: "mdbase-collections-dialog-error",
+      role: "alert",
+      children: error
+    })]
+  });
+}
+/** Sign-out found changes that haven't reached mdbase: wait, or sign out and lose them here. */
+export function SignOutDialog({
+  ui
+}) {
+  const problem = ui.signOutPrompt;
+  if (!problem) return null;
+  return _jsx(CollectionDialog, {
+    alert: true,
+    title: problem.title,
+    onClose: ui.actions.dismissSignOut,
+    footer: _jsxs(_Fragment, {
+      children: [_jsx(ActionButton, {
+        tone: "primary",
+        onClick: ui.actions.dismissSignOut,
+        children: problem.actionLabel ?? ui.copy.cancel
+      }), _jsx(ActionButton, {
+        tone: "danger",
+        onClick: ui.actions.confirmSignOut,
+        children: ui.copy.signOutAnyway
+      })]
+    }),
+    children: _jsx("p", {
+      children: problem.message
+    })
+  });
+}
+export function RowDialogs({
+  ui,
+  dialog,
+  onClose
+}) {
+  if (!dialog) return null;
+  return dialog.kind === "forget" ? _jsx(ForgetCollectionDialog, {
+    ui: ui,
+    collection: dialog.row,
+    onClose: onClose
+  }) : _jsx(DeleteCollectionDialog, {
+    ui: ui,
+    collection: dialog.row,
+    onClose: outcome => {
+      onClose();
+      dialog.onClose?.(outcome);
+    }
+  });
+}

package/dist/collections/model.d.ts

@@ -0,0 +1,146 @@
+import "../i18n.js";
+/**
+ * The headless collection view: one pure mapping from the SDK snapshot (whose
+ * `phase` already says what state the app is in) to what the shared screens
+ * show. No React, DOM or IO; the SDK owns state and problem copy, this module
+ * only chooses headings, lists and which SDK call each control makes.
+ */
+import type { MdbaseLinks, MdbasePhase, MdbaseProblem, MdbaseSnapshot } from "@mdbase-dev/sdk";
+import { type CollectionCopy } from "./copy.js";
+export type CollectionRole = "owner" | "editor" | "viewer";
+/** One approved collection, ready to render as a list row. */
+export interface CollectionRow {
+    readonly id: string;
+    readonly name: string;
+    /** Set when another listed collection has the same name. */
+    readonly disambiguator: string | null;
+    readonly role: CollectionRole;
+    readonly roleLabel: string;
+    /** A Private collection: kept on the person's computers and reached through
+     * the relay (the SDK entry's `kind: "private"`), not a hosted one. */
+    readonly private: boolean;
+    /** The collection that is open, or opening. */
+    readonly current: boolean;
+    readonly available: boolean;
+    /** Availability in a few words ("Your computer isn't online"), or null when available. */
+    readonly status: string | null;
+    /** The longer explanation for an unavailable collection. */
+    readonly statusDetail: string | null;
+    /** The SDK's entry, for app-derived details (see `rowDetail`). */
+    readonly entry: MdbaseSnapshot["collections"][number];
+}
+/** What a problem's own button does. Every SDK action maps to one control or none. */
+export type ProblemControl = {
+    readonly kind: "sign_in";
+    readonly label: string;
+} | {
+    readonly kind: "approve";
+    readonly label: string;
+    readonly collectionId: string | null;
+} | {
+    readonly kind: "choose_another";
+    readonly label: string;
+} | {
+    readonly kind: "set_up";
+    readonly label: string;
+} | {
+    readonly kind: "assess";
+    readonly label: string;
+} | {
+    readonly kind: "start";
+    readonly label: string;
+} | {
+    readonly kind: "reload";
+    readonly label: string;
+} | {
+    readonly kind: "link";
+    readonly label: string;
+    readonly href: string;
+};
+/** A described problem plus its control. `title`/`message` are the SDK's copy. */
+export interface CollectionNotice {
+    readonly key: string;
+    readonly tone: "info" | "warning" | "error";
+    readonly title: string | null;
+    readonly message: string;
+    readonly control: ProblemControl | null;
+    /** The SDK clears it by itself (busy, migrating): show it quietly. */
+    readonly transient: boolean;
+}
+interface Common {
+    /** The gate's heading for this phase (never an SDK problem title). */
+    readonly heading: string;
+    readonly lead: string | null;
+    /** Signed in to mdbase on this device. */
+    readonly signedIn: boolean;
+    /** "Signed in as …" label, or null when not signed in (or the account has no label). */
+    readonly account: string | null;
+    /** Every approved collection, current first then by name. */
+    readonly collections: readonly CollectionRow[];
+    readonly current: CollectionRow | null;
+    readonly links: MdbaseLinks | null;
+    /** True when "Choose a different collection" leaves something open or requested. */
+    readonly canChooseAnother: boolean;
+}
+export type CollectionView = Common & ({
+    readonly kind: "starting";
+} | {
+    readonly kind: "signed_out";
+    readonly notice: CollectionNotice | null;
+} | {
+    readonly kind: "authorizing";
+    readonly purpose: "sign_in" | "add" | "approve";
+    readonly collectionId: string | null;
+} | {
+    readonly kind: "choosing";
+    readonly notice: CollectionNotice | null;
+} | {
+    readonly kind: "opening";
+    readonly collectionId: string;
+    readonly slow: boolean;
+} | {
+    readonly kind: "needs_approval";
+    readonly collectionId: string;
+    readonly declined: boolean;
+} | {
+    readonly kind: "needs_setup";
+    readonly collectionId: string;
+} | {
+    readonly kind: "problem";
+    readonly collectionId: string | null;
+    readonly notice: CollectionNotice;
+} | {
+    readonly kind: "ready";
+    readonly collectionId: string;
+    readonly phase: Extract<MdbasePhase, {
+        kind: "ready";
+    }>;
+    readonly notice: CollectionNotice | null;
+} | {
+    readonly kind: "unavailable";
+    readonly notice: CollectionNotice;
+} | {
+    readonly kind: "closed";
+});
+export type CollectionViewKind = CollectionView["kind"];
+export interface CollectionViewOptions {
+    /** The app's name, as people know it ("TaskNotes"). */
+    readonly appName: string;
+    readonly copy?: Partial<CollectionCopy> | undefined;
+}
+type Snapshot = Pick<MdbaseSnapshot, "phase" | "collections" | "signIn" | "selection" | "links" | "readiness" | "status"> & Partial<Pick<MdbaseSnapshot, "signOutResult" | "selectedCollectionId">>;
+/** Map an SDK snapshot to the screen to show. */
+export declare function collectionView(snapshot: Snapshot, options: CollectionViewOptions): CollectionView;
+/** The SDK's description of a failed action, as an inline notice (no control: the person clicks again). */
+export declare function actionNotice(problem: MdbaseProblem | null): CollectionNotice | null;
+/** One control per SDK action; `wait`, `none` and actions with nowhere to go get none. */
+export declare function problemControl(problem: Pick<MdbaseProblem, "action" | "actionLabel" | "updateUrl">, context: {
+    collectionId: string | null;
+    signedIn: boolean;
+    open: boolean;
+}): ProblemControl | null;
+/** Rows for the approved collections: current first, then by name; equal names get an ID hint. */
+export declare function collectionRows(collections: MdbaseSnapshot["collections"], currentId: string | null, copy?: CollectionCopy): CollectionRow[];
+/** "someone@example.com", or "octocat on GitHub". */
+export declare function accountLabel(signIn: MdbaseSnapshot["signIn"]): string | null;
+export {};

package/dist/collections/model.js

@@ -0,0 +1,337 @@
+import { i18n as _i18n } from "@lingui/core";
+import "../i18n.js";
+import { describeError } from "@mdbase-dev/sdk/describe";
+import { defaultCollectionCopy, fill } from "./copy.js";
+/** Map an SDK snapshot to the screen to show. */
+export function collectionView(snapshot, options) {
+  const copy = {
+    ...defaultCollectionCopy,
+    ...options.copy
+  };
+  const app = options.appName;
+  const phase = snapshot.phase;
+  const currentId = currentCollectionId(phase);
+  const collections = collectionRows(snapshot.collections, currentId, copy);
+  const current = collections.find(row => row.current) ?? null;
+  const nameOf = (id, fallback = null) => id && collections.find(row => row.id === id)?.name || fallback;
+  const signedIn = snapshot.signIn?.state === "paired";
+  const say = (template, collection) => fill(template, {
+    app,
+    collection: collection ?? ""
+  });
+  const common = {
+    signedIn,
+    account: signedIn ? accountLabel(snapshot.signIn) : null,
+    collections,
+    current,
+    links: snapshot.links ?? null,
+    canChooseAnother: signedIn && (currentId !== null || (snapshot.selection.requested.collectionId ?? null) !== null)
+  };
+  switch (phase.kind) {
+    case "starting":
+      return {
+        ...common,
+        kind: "starting",
+        heading: say(copy.startingHeading),
+        lead: null
+      };
+    case "signed_out":
+      {
+        const signedOut = snapshot.signOutResult ?? null;
+        const notice = phase.notice ? quietNotice(phase.notice) : signedOut ? {
+          key: "signed_out",
+          tone: "info",
+          title: null,
+          control: null,
+          transient: false,
+          message: signedOut.server === "incomplete" ? `${say(copy.signedOutNotice)} ${copy.signedOutIncomplete}` : say(copy.signedOutNotice)
+        } : null;
+        return {
+          ...common,
+          kind: "signed_out",
+          heading: say(copy.signedOutHeading),
+          lead: say(copy.signedOutLead),
+          notice
+        };
+      }
+    case "authorizing":
+      {
+        const name = nameOf(phase.collectionId, snapshot.selection.requested.displayName) ?? copy.thisCollection;
+        const lead = phase.purpose === "sign_in" ? copy.authorizingSignIn : phase.purpose === "add" ? copy.authorizingAdd : copy.authorizingApprove;
+        return {
+          ...common,
+          kind: "authorizing",
+          purpose: phase.purpose,
+          collectionId: phase.collectionId,
+          heading: say(copy.authorizingHeading),
+          lead: say(lead, name)
+        };
+      }
+    case "choosing":
+      {
+        const empty = collections.length === 0;
+        return {
+          ...common,
+          kind: "choosing",
+          notice: approvalNotice(phase.lastApproval, copy),
+          heading: say(empty ? copy.emptyHeading : copy.chooseHeading),
+          lead: empty ? say(copy.emptyLead) : null
+        };
+      }
+    case "opening":
+      {
+        const name = nameOf(phase.collectionId, phase.displayName);
+        // Older SDKs omit progress. Only fixed SDK stages select localized copy;
+        // never render a remote string or infer progress from elapsed time.
+        const progressCopy = {
+          joining: copy.openingJoining,
+          opening_store: copy.openingStore,
+          connecting_log: copy.openingLog,
+          syncing: copy.openingSyncing,
+          loading_snapshot: copy.openingSnapshot,
+          replaying: copy.openingReplaying,
+          waiting_for_key: copy.openingKey,
+          verifying_read: copy.openingRead,
+          checking_setup: copy.openingSetup
+        };
+        const progress = "progress" in phase ? phase.progress : null;
+        const detail = typeof progress === "string" && Object.hasOwn(progressCopy, progress) ? progressCopy[progress] : null;
+        return {
+          ...common,
+          kind: "opening",
+          collectionId: phase.collectionId,
+          slow: phase.slow,
+          heading: name ? say(copy.openingHeading, name) : say(copy.openingHeadingUnnamed),
+          lead: detail ? [say(detail), ...(phase.slow ? [say(copy.openingSlow)] : [])].join("\n") : phase.slow ? say(copy.openingSlow) : null
+        };
+      }
+    case "needs_approval":
+      {
+        const name = nameOf(phase.collectionId, phase.displayName);
+        return {
+          ...common,
+          kind: "needs_approval",
+          collectionId: phase.collectionId,
+          declined: phase.declined,
+          heading: name ? say(copy.approvalHeading, name) : say(copy.approvalHeadingUnnamed),
+          lead: say(phase.declined ? copy.approvalDeclined : copy.approvalLead)
+        };
+      }
+    case "needs_setup":
+      {
+        const name = nameOf(phase.collectionId, phase.collection.displayName);
+        return {
+          ...common,
+          kind: "needs_setup",
+          collectionId: phase.collectionId,
+          heading: say(copy.setupHeading, name),
+          lead: say(copy.setupLead)
+        };
+      }
+    case "problem":
+      {
+        const name = nameOf(phase.collectionId, snapshot.selection.requested.displayName);
+        const notice = problemNotice(phase.problem, {
+          collectionId: phase.collectionId,
+          signedIn,
+          open: isOpen(snapshot)
+        });
+        return {
+          ...common,
+          kind: "problem",
+          collectionId: phase.collectionId,
+          notice,
+          heading: name ? say(copy.problemHeading, name) : say(copy.problemHeadingUnnamed),
+          lead: null
+        };
+      }
+    case "ready":
+      return {
+        ...common,
+        kind: "ready",
+        collectionId: phase.collectionId,
+        phase,
+        notice: phase.problem ? problemNotice(phase.problem, {
+          collectionId: phase.collectionId,
+          signedIn,
+          open: true
+        }) : null,
+        heading: phase.collection.displayName,
+        lead: null
+      };
+    case "unavailable":
+      return {
+        ...common,
+        kind: "unavailable",
+        notice: problemNotice(phase.problem, {
+          collectionId: null,
+          signedIn: false,
+          open: false
+        }),
+        heading: say(copy.unavailableHeading),
+        lead: null
+      };
+    case "closed":
+      return {
+        ...common,
+        kind: "closed",
+        heading: say(copy.closedHeading),
+        lead: say(copy.closedLead)
+      };
+  }
+}
+/** The SDK's description of a failed action, as an inline notice (no control: the person clicks again). */
+export function actionNotice(problem) {
+  return problem ? quietNotice(problem) : null;
+}
+function quietNotice(problem) {
+  return {
+    key: problem.key,
+    tone: problem.severity,
+    title: problem.title,
+    message: problem.message,
+    control: null,
+    transient: problem.transient
+  };
+}
+function problemNotice(problem, context) {
+  return {
+    ...quietNotice(problem),
+    control: problemControl(problem, context)
+  };
+}
+/** One control per SDK action; `wait`, `none` and actions with nowhere to go get none. */
+export function problemControl(problem, context) {
+  const label = problem.actionLabel;
+  if (!label) return null;
+  const action = problem.action;
+  switch (action) {
+    case "sign_in":
+      return {
+        kind: "sign_in",
+        label
+      };
+    case "approve":
+      return {
+        kind: "approve",
+        label,
+        collectionId: context.collectionId
+      };
+    case "choose_collection":
+      return context.signedIn ? {
+        kind: "choose_another",
+        label
+      } : null;
+    case "set_up":
+      return context.open ? {
+        kind: "set_up",
+        label
+      } : null;
+    case "update_app":
+      return problem.updateUrl ? {
+        kind: "link",
+        label,
+        href: problem.updateUrl
+      } : null;
+    case "retry":
+    case "check_connection":
+      return context.open ? {
+        kind: "assess",
+        label
+      } : {
+        kind: "start",
+        label
+      };
+    case "resolve_outcome":
+      return {
+        kind: "start",
+        label
+      };
+    case "reload":
+      return {
+        kind: "reload",
+        label
+      };
+    case "wait":
+    case "free_space":
+    case "contact_support":
+    case "none":
+      return null;
+  }
+}
+function approvalNotice(outcome, copy) {
+  if (!outcome || outcome.outcome === "added" || outcome.outcome === "unchanged") return null;
+  const message = outcome.kind === "add" ? copy.noCollectionAdded : copy.accessNotGiven;
+  return {
+    key: `approval_${outcome.outcome}`,
+    tone: "info",
+    title: null,
+    message,
+    control: null,
+    transient: false
+  };
+}
+function currentCollectionId(phase) {
+  switch (phase.kind) {
+    case "opening":
+    case "needs_setup":
+    case "ready":
+      return phase.collectionId;
+    case "problem":
+      return phase.collectionId;
+    default:
+      return null;
+  }
+}
+function isOpen(snapshot) {
+  return snapshot.status === "ready" || snapshot.status === "setup_required";
+}
+const roleLabels = copy => ({
+  owner: copy.roleOwner,
+  editor: copy.roleEditor,
+  viewer: copy.roleViewer
+});
+/** Rows for the approved collections: current first, then by name; equal names get an ID hint. */
+export function collectionRows(collections, currentId, copy = defaultCollectionCopy) {
+  const counts = new Map();
+  for (const c of collections) counts.set(c.displayName.trim().toLocaleLowerCase(), (counts.get(c.displayName.trim().toLocaleLowerCase()) ?? 0) + 1);
+  const roles = roleLabels(copy);
+  const rows = collections.map(c => {
+    const availability = c.availability ?? {
+      state: "available"
+    };
+    const unavailable = availability.state === "unavailable";
+    const described = unavailable ? describeError(availability) : null;
+    return {
+      id: c.collectionId,
+      name: c.displayName,
+      disambiguator: (counts.get(c.displayName.trim().toLocaleLowerCase()) ?? 0) > 1 ? fill(copy.idHint, {
+        id: c.collectionId.slice(0, 8)
+      }) : null,
+      role: c.role,
+      roleLabel: roles[c.role],
+      private: c.kind === "private",
+      current: c.collectionId === currentId,
+      available: !unavailable,
+      status: availability.state === "opening" ? copy.rowOpening : described?.title ?? null,
+      statusDetail: described?.message ?? null,
+      entry: c
+    };
+  });
+  return rows.sort((a, b) => Number(b.current) - Number(a.current) || a.name.localeCompare(b.name) || a.id.localeCompare(b.id));
+}
+/** "someone@example.com", or "octocat on GitHub". */
+export function accountLabel(signIn) {
+  if (!signIn) return null;
+  if (signIn.accountEmail) return signIn.accountEmail;
+  if (signIn.accountProvider === "github" && signIn.accountLogin) return _i18n._(
+  /** i18n */
+  {
+    id: "yObBTM",
+    message: "{0} on GitHub",
+    values: {
+      0: signIn.accountLogin
+    }
+  });
+  return null;
+}

package/dist/collections/mount.d.ts

@@ -0,0 +1,19 @@
+import { type CollectionSwitcherProps } from "./CollectionSwitcher.js";
+import type { CollectionUiOptions } from "./use-collection-ui.js";
+export type CollectionUiPart = "panel" | "switcher" | "problem";
+export interface MountCollectionUiOptions extends CollectionUiOptions {
+    /** "panel": sign-in, choosing and the list (a settings dialog); "switcher": the header trigger; "problem": the current problem with its fix. */
+    readonly part: CollectionUiPart;
+    /** "switcher": the trigger's variant. "none" needs an app anchor, so it is not mountable. */
+    readonly variant?: Exclude<CollectionSwitcherProps["variant"], "none">;
+    /** "switcher": leading content in the trigger ("mark" for the collection's initials). */
+    readonly icon?: CollectionSwitcherProps["icon"];
+    /** "panel": call `mdbase.start()` when it hasn't started. Default true. */
+    readonly autoStart?: boolean;
+}
+export interface MountedCollectionUi {
+    update(next: Partial<MountCollectionUiOptions>): void;
+    unmount(): void;
+}
+/** Render a shared collection component into an element, for apps that don't render with React. */
+export declare function mountCollectionUi(element: Element, options: MountCollectionUiOptions): MountedCollectionUi;