@paroicms/public-admin-ui-lib

Common utilitaries for paroicms plugins (admin-ui side).

This package is part of ParoiCMS.

Top-sidebar blocks

An Admin UI plugin can register one or more framework-neutral DOM blocks below the site header. A plugin that registers only sidebar blocks is valid.

import type {
  AdminUiPlugin,
  AdminUiTopSidebarBlockFactory,
} from "@paroicms/public-admin-ui-lib";

const createBlock: AdminUiTopSidebarBlockFactory = (service, initialContext) => {
  const element = document.createElement("section");
  const link = document.createElement("a");
  element.append(link);

  function setContext(context = initialContext) {
    const item = context.currentItem;
    if (!item) {
      element.hidden = true;
      return;
    }
    const document = item.kind === "document" ? item : item.document;
    const payload = { documentId: document.documentId, typeName: document.typeName, tab: "edit" } as const;
    element.hidden = false;
    link.href = service.getDocumentEditionUrl(payload);
    link.textContent = "Open document";
    link.onclick = (event) => {
      if (event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
      event.preventDefault();
      service.openDocumentEdition(payload);
    };
  }

  setContext();
  return {
    element,
    setContext,
    dispose() {
      link.onclick = null;
    },
  };
};

const plugin: AdminUiPlugin = {
  init(service) {
    service.registerTopSidebarBlock(createBlock);
  },
};

export default plugin;

Factories run in configured plugin order and registration order. Each factory receives the authenticated plugin service and an initial context. The same instance survives normal Admin UI navigation and sidebar host replacement. setContext calls are serialized and intermediate queued contexts can be replaced by the newest one. dispose runs once when the authenticated plugin session ends.

The context always contains contentLanguage and homeRoutingCluster. Document routes add the current document, its schema type, and current routing cluster. A selected part replaces the current item and schema type with the part while retaining a reference to its containing document. Dashboard and settings routes omit currentItem, nodeType, and routingCluster.

One failing factory or lifecycle method does not affect other contributions or native sidebar navigation. Plugins should still handle their own data and event-listener cleanup.

The authenticated service also provides:

• listChildDocuments for paginated, sorted direct children with optional selected field values.
• getRoutingCluster for a document that roots a cluster.
• getDocumentEditionUrl for semantic browser links.
• openDocumentEdition for same-tab SPA navigation to the same target. It accepts either the payload used by getDocumentEditionUrl or the compatible (documentId, typeName) arguments.

Use semantic buttons and anchors, visible :focus-visible styles, and wrapped text. Blocks should fit their container at narrow widths. The Admin UI exposes design variables including --color-bg-sidebar, --color-text-sidebar, --color-text-sidebar-muted, --color-primary, --space-*, and --radius-*; these adapt to the active sidebar theme.

License

Released under the MIT license.