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

package/dist/collections/mount.js

@@ -0,0 +1,56 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createRoot } from "react-dom/client";
+import { CollectionPanel, CollectionProblem } from "./CollectionGate.js";
+import { CollectionSwitcher } from "./CollectionSwitcher.js";
+/** Render a shared collection component into an element, for apps that don't render with React. */
+export function mountCollectionUi(element, options) {
+  const root = createRoot(element);
+  let current = options;
+  const render = () => root.render(_jsx(Part, {
+    ...current
+  }));
+  render();
+  return {
+    update(next) {
+      current = {
+        ...current,
+        ...next
+      };
+      render();
+    },
+    unmount() {
+      root.unmount();
+    }
+  };
+}
+function Part({
+  part,
+  variant,
+  icon,
+  autoStart,
+  ...options
+}) {
+  switch (part) {
+    case "panel":
+      return _jsx(CollectionPanel, {
+        ...options,
+        ...(autoStart === undefined ? {} : {
+          autoStart
+        })
+      });
+    case "switcher":
+      return _jsx(CollectionSwitcher, {
+        ...options,
+        ...(variant ? {
+          variant
+        } : {}),
+        ...(icon === undefined ? {} : {
+          icon
+        })
+      });
+    case "problem":
+      return _jsx(CollectionProblem, {
+        ...options
+      });
+  }
+}

package/dist/collections/parts.d.ts

@@ -0,0 +1,86 @@
+import { type JSX, type ReactNode } from "react";
+import type { CollectionNotice, CollectionRow } from "./model.js";
+import type { CollectionSectionItem, CollectionUi, DeleteCollectionOutcome } from "./use-collection-ui.js";
+/** Which row dialog is open, shared by the gate and the switcher. `onClose` hears a delete's outcome. */
+export type RowDialog = {
+    readonly kind: "forget" | "delete";
+    readonly row: Pick<CollectionRow, "id" | "name">;
+    readonly onClose?: ((outcome: DeleteCollectionOutcome) => void) | undefined;
+} | null;
+export type ButtonTone = "primary" | "secondary" | "quiet" | "danger";
+/**
+ * A text button. While another action runs it stays focusable but inert
+ * (`aria-disabled`), and the running one shows its progress label.
+ */
+export declare function ActionButton({ tone, inert, progress, onClick, children, className, ...rest }: {
+    readonly tone?: ButtonTone;
+    readonly inert?: boolean;
+    /** Shown instead of the label while this button's own action runs. */
+    readonly progress?: string | null | undefined;
+    readonly onClick: () => void;
+    readonly children: ReactNode;
+    readonly className?: string;
+    readonly "aria-describedby"?: string | undefined;
+}): JSX.Element;
+/** One problem with its own fix: SDK title and message, then the SDK action as a button inside the block. */
+export declare function NoticeBlock({ notice, ui, onSetUp, variant }: {
+    readonly notice: CollectionNotice;
+    readonly ui: CollectionUi;
+    readonly onSetUp?: (() => void) | undefined;
+    readonly variant?: "block" | "banner" | "inline";
+}): JSX.Element;
+/** Initials on a hue that stays the same for a collection across sessions. */
+export declare function CollectionMark({ row }: {
+    readonly row: Pick<CollectionRow, "id" | "name">;
+}): JSX.Element;
+/** The name (wrapping, never truncated), the app's optional second line, then one line of role and availability. */
+export declare function RowCopy({ row, ui, detailId, current }: {
+    readonly row: CollectionRow;
+    readonly ui: CollectionUi;
+    readonly detailId?: string;
+    /** Overrides `row.current` (an app section item is open instead). */
+    readonly current?: boolean;
+}): JSX.Element;
+/** Marks a Private collection: a visible label, read with the row's name. */
+export declare function PrivateMark({ ui }: {
+    readonly ui: CollectionUi;
+}): JSX.Element;
+/** An app section item: its name and optional second line. */
+export declare function ItemCopy({ item, ui }: {
+    readonly item: CollectionSectionItem;
+    readonly ui: CollectionUi;
+}): JSX.Element;
+/** "Remove from this list" and, for owners when allowed, "Delete collection…". */
+export declare function RowMore({ row, ui, onDialog, tabbable }: {
+    readonly row: CollectionRow;
+    readonly ui: CollectionUi;
+    readonly onDialog: (dialog: NonNullable<RowDialog>) => void;
+    readonly tabbable?: boolean;
+}): JSX.Element;
+/** An app section item's own actions, in the same row menu as an SDK collection's. */
+export declare function ItemMore({ item, ui, onDialog, tabbable }: {
+    readonly item: CollectionSectionItem;
+    readonly ui: CollectionUi;
+    readonly onDialog: (dialog: NonNullable<RowDialog>) => void;
+    readonly tabbable?: boolean;
+}): JSX.Element | null;
+/** The app's actions, Choose a different collection, Manage access, the account and Sign out: never under an error. */
+export declare function GateFooter({ ui, chooseAnother, extra }: {
+    readonly ui: CollectionUi;
+    readonly chooseAnother: boolean;
+    readonly extra?: ReactNode;
+}): JSX.Element | null;
+export declare function AccountLine({ ui }: {
+    readonly ui: CollectionUi;
+}): JSX.Element;
+/** A native modal <dialog>: the browser traps focus and makes the page inert; Escape cancels. */
+export declare function CollectionDialog({ title, alert, busy, onClose, children, footer }: {
+    readonly title: string;
+    readonly alert?: boolean;
+    readonly busy?: boolean;
+    readonly onClose: () => void;
+    readonly children: ReactNode;
+    readonly footer: ReactNode;
+}): JSX.Element;
+export declare function initials(name: string): string;
+export declare function hueOf(id: string): number;

package/dist/collections/parts.js

@@ -0,0 +1,439 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useId, useLayoutEffect, useRef, useState } from "react";
+import { moveMenuFocus, useMenuPopover } from "../popover.js";
+/**
+ * A text button. While another action runs it stays focusable but inert
+ * (`aria-disabled`), and the running one shows its progress label.
+ */
+export function ActionButton({
+  tone = "secondary",
+  inert = false,
+  progress,
+  onClick,
+  children,
+  className,
+  ...rest
+}) {
+  const label = progress ?? children;
+  return _jsx("button", {
+    type: "button",
+    className: ["mdbase-collections-button", `is-${tone}`, className].filter(Boolean).join(" "),
+    "aria-disabled": inert || progress ? true : undefined,
+    onClick: () => {
+      if (!inert && !progress) onClick();
+    },
+    ...rest,
+    children: label
+  });
+}
+/** One problem with its own fix: SDK title and message, then the SDK action as a button inside the block. */
+export function NoticeBlock({
+  notice,
+  ui,
+  onSetUp,
+  variant = "block"
+}) {
+  const control = notice.control && (notice.control.kind !== "set_up" || onSetUp) ? notice.control : null;
+  const urgent = !notice.transient && notice.tone !== "info";
+  return _jsxs("div", {
+    className: `mdbase-collections-notice is-${variant}`,
+    "data-tone": notice.tone,
+    role: urgent ? "alert" : "status",
+    children: [_jsxs("div", {
+      className: "mdbase-collections-notice-copy",
+      children: [notice.title && _jsx("p", {
+        className: "mdbase-collections-notice-title",
+        children: notice.title
+      }), _jsx("p", {
+        className: "mdbase-collections-notice-message",
+        children: notice.message
+      })]
+    }), control && _jsx("div", {
+      className: "mdbase-collections-notice-actions",
+      children: _jsx(ControlButton, {
+        control: control,
+        ui: ui,
+        onSetUp: onSetUp
+      })
+    })]
+  });
+}
+function ControlButton({
+  control,
+  ui,
+  onSetUp
+}) {
+  if (control.kind === "link") {
+    return _jsx("a", {
+      className: "mdbase-collections-button is-primary",
+      href: control.href,
+      target: "_blank",
+      rel: "noopener noreferrer",
+      children: control.label
+    });
+  }
+  return _jsx(ActionButton, {
+    tone: "primary",
+    inert: ui.busy !== null,
+    onClick: () => ui.actions.perform(control, onSetUp),
+    children: control.label
+  });
+}
+/** Initials on a hue that stays the same for a collection across sessions. */
+export function CollectionMark({
+  row
+}) {
+  return _jsx("span", {
+    className: "mdbase-collections-mark",
+    "aria-hidden": "true",
+    style: {
+      "--mdbase-collections-hue": hueOf(row.id)
+    },
+    children: initials(row.name)
+  });
+}
+/** The name (wrapping, never truncated), the app's optional second line, then one line of role and availability. */
+export function RowCopy({
+  row,
+  ui,
+  detailId,
+  current = row.current
+}) {
+  const meta = [current ? ui.copy.openNow : null, row.roleLabel, row.status].filter(Boolean).join(" · ");
+  const secondary = ui.options.rowDetail?.(row);
+  return _jsxs("span", {
+    className: "mdbase-collections-row-copy",
+    children: [_jsxs("span", {
+      className: "mdbase-collections-row-name",
+      children: [row.name, row.disambiguator && _jsxs("span", {
+        className: "mdbase-collections-row-hint",
+        children: [" ", row.disambiguator]
+      }), row.private && _jsxs(_Fragment, {
+        children: [" ", _jsx(PrivateMark, {
+          ui: ui
+        })]
+      })]
+    }), secondary && _jsx("span", {
+      className: "mdbase-collections-row-secondary",
+      children: secondary
+    }), _jsx("span", {
+      className: "mdbase-collections-row-meta",
+      children: meta
+    }), row.statusDetail && _jsx("span", {
+      className: "mdbase-collections-row-detail",
+      id: detailId,
+      children: row.statusDetail
+    })]
+  });
+}
+/** Marks a Private collection: a visible label, read with the row's name. */
+export function PrivateMark({
+  ui
+}) {
+  return _jsxs("span", {
+    className: "mdbase-collections-chip mdbase-collections-private",
+    title: ui.copy.privateCollectionHint,
+    children: [_jsx("svg", {
+      viewBox: "0 0 16 16",
+      "aria-hidden": "true",
+      children: _jsx("path", {
+        d: "M4.5 7.5h7v5.5h-7zM6 7.5V5.5a2 2 0 0 1 4 0v2"
+      })
+    }), ui.copy.privateCollection]
+  });
+}
+/** An app section item: its name and optional second line. */
+export function ItemCopy({
+  item,
+  ui
+}) {
+  return _jsxs("span", {
+    className: "mdbase-collections-row-copy",
+    children: [_jsx("span", {
+      className: "mdbase-collections-row-name",
+      children: item.name
+    }), item.detail && _jsx("span", {
+      className: "mdbase-collections-row-secondary",
+      children: item.detail
+    }), item.current && _jsx("span", {
+      className: "mdbase-collections-row-meta",
+      children: ui.copy.openNow
+    })]
+  });
+}
+/** "Remove from this list" and, for owners when allowed, "Delete collection…". */
+export function RowMore({
+  row,
+  ui,
+  onDialog,
+  tabbable = true
+}) {
+  const canDelete = ui.options.allowDelete === true && row.role === "owner";
+  const entries = [{
+    id: "forget",
+    label: ui.copy.removeFromList,
+    onSelect: () => onDialog({
+      kind: "forget",
+      row
+    })
+  }];
+  if (canDelete) entries.push({
+    id: "delete",
+    label: ui.copy.deleteCollection,
+    danger: true,
+    onSelect: () => onDialog({
+      kind: "delete",
+      row
+    })
+  });
+  return _jsx(RowMenuButton, {
+    label: ui.say("moreFor", {
+      collection: row.name
+    }),
+    entries: entries,
+    tabbable: tabbable
+  });
+}
+/** An app section item's own actions, in the same row menu as an SDK collection's. */
+export function ItemMore({
+  item,
+  ui,
+  onDialog,
+  tabbable = true
+}) {
+  const actions = item.actions ?? [];
+  if (actions.length === 0) return null;
+  const context = {
+    confirmDelete: onClose => onDialog({
+      kind: "delete",
+      row: item,
+      onClose
+    })
+  };
+  const entries = actions.map(action => ({
+    id: action.id,
+    label: action.label,
+    danger: action.danger,
+    disabled: action.disabled,
+    onSelect: () => action.onSelect(item, context)
+  }));
+  return _jsx(RowMenuButton, {
+    label: ui.say("moreFor", {
+      collection: item.name
+    }),
+    entries: entries,
+    tabbable: tabbable,
+    refocus: true
+  });
+}
+/**
+ * A row's "…" button and its menu. Arrow keys move between enabled entries,
+ * Escape closes it and returns focus to the button; with `refocus`, choosing an
+ * entry returns focus there too, so a dialog it opens hands focus back to it.
+ */
+function RowMenuButton({
+  label,
+  entries,
+  tabbable,
+  refocus = false
+}) {
+  const [open, setOpen] = useState(false);
+  const trigger = useRef(null);
+  const menuId = useId();
+  const close = focus => {
+    setOpen(false);
+    if (focus) trigger.current?.focus();
+  };
+  return _jsxs(_Fragment, {
+    children: [_jsx("button", {
+      ref: trigger,
+      type: "button",
+      className: "mdbase-collections-more",
+      "aria-label": label,
+      "aria-haspopup": "menu",
+      "aria-expanded": open,
+      "aria-controls": open ? menuId : undefined,
+      tabIndex: tabbable ? 0 : -1,
+      onClick: () => setOpen(value => !value),
+      children: _jsxs("svg", {
+        viewBox: "0 0 16 16",
+        "aria-hidden": "true",
+        children: [_jsx("circle", {
+          cx: "3.5",
+          cy: "8",
+          r: "1.3"
+        }), _jsx("circle", {
+          cx: "8",
+          cy: "8",
+          r: "1.3"
+        }), _jsx("circle", {
+          cx: "12.5",
+          cy: "8",
+          r: "1.3"
+        })]
+      })
+    }), open && _jsx(RowMenu, {
+      id: menuId,
+      triggerRef: trigger,
+      onClose: close,
+      children: entries.map(entry => _jsx("button", {
+        type: "button",
+        role: "menuitem",
+        disabled: entry.disabled,
+        className: entry.danger ? "mdbase-collections-menu-item is-danger" : "mdbase-collections-menu-item",
+        onClick: () => {
+          if (entry.disabled) return;
+          close(refocus);
+          entry.onSelect();
+        },
+        children: entry.label
+      }, entry.id))
+    })]
+  });
+}
+function RowMenu({
+  id,
+  triggerRef,
+  onClose,
+  children
+}) {
+  const menu = useRef(null);
+  useMenuPopover(menu, triggerRef, onClose, {
+    align: "end",
+    focus: '[role="menuitem"]'
+  });
+  return _jsx("div", {
+    ref: menu,
+    id: id,
+    className: "mdbase-collections-menu",
+    popover: "manual",
+    role: "menu",
+    tabIndex: -1,
+    onKeyDown: event => moveMenuFocus(event, menu.current),
+    children: children
+  });
+}
+/** The app's actions, Choose a different collection, Manage access, the account and Sign out: never under an error. */
+export function GateFooter({
+  ui,
+  chooseAnother,
+  extra
+}) {
+  const {
+    view,
+    copy,
+    busy,
+    actions
+  } = ui;
+  const hasExtra = extra !== undefined && extra !== null && extra !== false;
+  if (!view.signedIn && !chooseAnother && !hasExtra) return null;
+  return _jsxs("footer", {
+    className: "mdbase-collections-footer",
+    children: [hasExtra && _jsx("span", {
+      className: "mdbase-collections-footer-extra",
+      children: extra
+    }), chooseAnother && _jsx(ActionButton, {
+      tone: "quiet",
+      inert: busy !== null,
+      progress: busy === "choose_another" ? copy.chooseAnother : null,
+      onClick: actions.chooseAnother,
+      children: copy.chooseAnother
+    }), view.signedIn && view.links && _jsx("a", {
+      className: "mdbase-collections-link",
+      href: view.links.manageAccess,
+      target: "_blank",
+      rel: "noopener noreferrer",
+      children: copy.manageAccess
+    }), view.signedIn && _jsx(AccountLine, {
+      ui: ui
+    })]
+  });
+}
+export function AccountLine({
+  ui
+}) {
+  const {
+    view,
+    copy,
+    busy,
+    actions,
+    say
+  } = ui;
+  return _jsxs("span", {
+    className: "mdbase-collections-account",
+    children: [view.account && _jsx("span", {
+      className: "mdbase-collections-account-label",
+      children: say("signedInAs", {
+        account: view.account
+      })
+    }), _jsx(ActionButton, {
+      tone: "quiet",
+      inert: busy !== null,
+      progress: busy === "sign_out" ? copy.signingOut : null,
+      onClick: actions.signOut,
+      children: copy.signOut
+    })]
+  });
+}
+/** A native modal <dialog>: the browser traps focus and makes the page inert; Escape cancels. */
+export function CollectionDialog({
+  title,
+  alert = false,
+  busy = false,
+  onClose,
+  children,
+  footer
+}) {
+  const ref = useRef(null);
+  const titleId = useId();
+  useLayoutEffect(() => {
+    const dialog = ref.current;
+    const previous = document.activeElement instanceof HTMLElement ? document.activeElement : null;
+    if (dialog && !dialog.open) {
+      if (typeof dialog.showModal === "function") dialog.showModal();else dialog.setAttribute("open", "");
+    }
+    (dialog?.querySelector("[data-autofocus]") ?? dialog?.querySelector("button"))?.focus();
+    return () => {
+      if (dialog?.open && typeof dialog.close === "function") dialog.close();
+      if (previous?.isConnected) previous.focus();
+    };
+  }, []);
+  return _jsxs("dialog", {
+    ref: ref,
+    className: "mdbase-collections mdbase-collections-dialog",
+    role: alert ? "alertdialog" : undefined,
+    "aria-labelledby": titleId,
+    onKeyDown: event => {
+      event.stopPropagation();
+      if (event.key === "Escape") {
+        event.preventDefault();
+        if (!busy) onClose();
+      }
+    },
+    onCancel: event => {
+      event.preventDefault();
+      if (!busy) onClose();
+    },
+    children: [_jsx("h2", {
+      id: titleId,
+      className: "mdbase-collections-dialog-title",
+      children: title
+    }), _jsx("div", {
+      className: "mdbase-collections-dialog-body",
+      children: children
+    }), _jsx("div", {
+      className: "mdbase-collections-dialog-actions",
+      children: footer
+    })]
+  });
+}
+export function initials(name) {
+  const words = name.replace(/[^\p{L}\p{N}\s]/gu, " ").trim().split(/\s+/u).filter(Boolean);
+  const letters = words.slice(0, 2).map(word => String.fromCodePoint(word.codePointAt(0) ?? 63));
+  return (letters.join("") || "?").toLocaleUpperCase();
+}
+export function hueOf(id) {
+  let hash = 0;
+  for (const code of id) hash = (hash * 31 + (code.codePointAt(0) ?? 0)) % 360;
+  return hash;
+}

package/dist/collections/testing.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `@mdbase-dev/ui/collections/testing`: for Node test runners that render the
+ * collection components without a DOM environment per file.
+ *
+ * The components' focus and popover code reads the global `window` and
+ * `document` (not the rendered element's `ownerDocument`), so the test's
+ * window must also be the global one.
+ */
+/**
+ * Make `window` (a jsdom or happy-dom window) the global window and document
+ * for the collection components. Returns a function that restores the
+ * previous globals.
+ *
+ * ```ts
+ * const restore = shareTestDocument(new JSDOM("<!doctype html><body></body>").window);
+ * afterAll(restore);
+ * ```
+ */
+export declare function shareTestDocument(window: object): () => void;

package/dist/collections/testing.js

@@ -0,0 +1,39 @@
+/**
+ * `@mdbase-dev/ui/collections/testing`: for Node test runners that render the
+ * collection components without a DOM environment per file.
+ *
+ * The components' focus and popover code reads the global `window` and
+ * `document` (not the rendered element's `ownerDocument`), so the test's
+ * window must also be the global one.
+ */
+const shared = ["window", "document", "navigator", "Node", "Element", "HTMLElement", "HTMLButtonElement", "HTMLDialogElement", "HTMLInputElement", "Event", "FocusEvent", "KeyboardEvent", "MouseEvent", "PointerEvent", "getComputedStyle", "matchMedia", "requestAnimationFrame", "cancelAnimationFrame"];
+/**
+ * Make `window` (a jsdom or happy-dom window) the global window and document
+ * for the collection components. Returns a function that restores the
+ * previous globals.
+ *
+ * ```ts
+ * const restore = shareTestDocument(new JSDOM("<!doctype html><body></body>").window);
+ * afterAll(restore);
+ * ```
+ */
+export function shareTestDocument(window) {
+  const global = globalThis;
+  const source = window;
+  const previous = new Map();
+  for (const name of shared) {
+    const value = name === "window" ? window : source[name];
+    if (value === undefined) continue;
+    previous.set(name, Object.getOwnPropertyDescriptor(globalThis, name));
+    Object.defineProperty(globalThis, name, {
+      configurable: true,
+      writable: true,
+      value: typeof value === "function" && /^[a-z]/.test(name) ? value.bind(window) : value
+    });
+  }
+  return () => {
+    for (const [name, descriptor] of previous) {
+      if (descriptor) Object.defineProperty(globalThis, name, descriptor);else delete global[name];
+    }
+  };
+}