@paroicms/public-admin-ui-lib 0.25.0

package/README.md

@@ -0,0 +1,9 @@
+# @paroicms/public-admin-ui-lib
+
+Common utilitaries for paroicms plugins (admin-ui side).
+
+This package is part of [ParoiCMS](https://www.npmjs.com/package/@paroicms/server).
+
+## License
+
+Released under the [MIT license](https://gitlab.com/paroi/opensource/paroicms/-/blob/main/LICENSE.md).

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from "../types/admin-ui-plugin-types.js";

package/dist/index.js

@@ -0,0 +1 @@
+export * from "../types/admin-ui-plugin-types.js";

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@paroicms/public-admin-ui-lib",
+  "version": "0.25.0",
+  "description": "Common utilitaries for paroicms plugins (admin UI side).",
+  "author": "Paroi Team",
+  "repository": {
+    "type": "git",
+    "url": "https://gitlab.com/paroi/opensource/paroicms.git",
+    "directory": "packages/public-admin-ui-lib"
+  },
+  "license": "MIT",
+  "type": "module",
+  "module": "dist/index.js",
+  "typings": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "clear": "rimraf dist/*",
+    "dev": "tsc --watch --preserveWatchOutput"
+  },
+  "dependencies": {
+    "@paroicms/public-anywhere-lib": "0.24.0"
+  },
+  "devDependencies": {
+    "rimraf": "~6.0.1",
+    "typescript": "~5.8.3"
+  },
+  "files": [
+    "dist",
+    "types"
+  ]
+}

package/types/admin-ui-plugin-types.d.ts

@@ -0,0 +1,156 @@
+import type {
+  MImageVariant,
+  MSourceImage,
+  MSourceMedia,
+  OrderByItem,
+  ReadFieldValue,
+  ResizeRule,
+  ScFieldType,
+  ThemeConf,
+  UpdateFieldValue,
+} from "@paroicms/public-anywhere-lib";
+
+export type AdminUiPlugin = {
+  init: (service: AdminUiPluginInitService) => void | Promise<void>;
+  create: (service: AdminUiPluginFieldService) => AdminUiPluginInstance;
+};
+
+export interface AdminUiPluginInitService {
+  logger: AdminUiLogger;
+  themeConf: ThemeConf;
+  publicSiteUrl: string;
+  configuration: {
+    [key: string]: unknown;
+  };
+  pluginBaseUrl: string;
+  registerHook(
+    hookName: string,
+    handler: AdminUiPluginHookHandler,
+    options?: { unique?: boolean },
+  ): void;
+  addAfterInitListener(listener: AdminUiPluginAfterInitListener): void;
+}
+
+export type AdminUiPluginAfterInitListener = (
+  service: AdminUiPluginService,
+) => void | Promise<void>;
+
+export type AdminUiPluginHookHandler = (service: AdminUiPluginService, params?: any) => any;
+
+export interface AdminUiPluginInstance {
+  element: HTMLElement;
+  setValue(value: ReadFieldValue | undefined): void;
+  setLanguage(language: string): void;
+  getValue(): UpdateFieldValue | undefined;
+  dispose(): void;
+  insertMedia?(media: MSourceMedia): Promise<void>;
+}
+
+export interface AdminUiPluginService {
+  themeConf: ThemeConf;
+  publicSiteUrl: string;
+  logger: AdminUiLogger;
+  configuration: {
+    [key: string]: unknown;
+  };
+  pluginBaseUrl: string;
+  createModalDialog<T = undefined>(dialog: PluginDialog): PluginDialogHandler<T>;
+  /**
+   * Notice: it's not safe to use admin-ui image variant URLs in a rendered web page. Use these
+   * variants only in the admin-ui. Image variants for rendered web pages must be re-rendered
+   * from the backend every time the web page is re-rendered. Look at the Quill plugin for an
+   * example. If you need to use an image variant from the admin-ui in a rendered web page, then
+   * pick `useFTextImage`.
+   */
+  useAdminUiImage(
+    image: string | MSourceImage,
+    options: {
+      resizeRule: ResizeRule;
+      pixelRatio?: number;
+      mediaType?: string;
+    },
+  ): Promise<AdminUiImageVariant | undefined>;
+  useFTextImage(
+    image: string | MSourceImage,
+    options: {
+      /** Must exists in the theme configuration. */
+      resizeRule: ResizeRule;
+    },
+  ): Promise<AdminUiImageVariant | undefined>;
+  showToast(message: string, options?: AdminUiToastOptions): void;
+  executeHook<T = unknown>(hookName: string, params?: any): T[];
+  searchDocuments(payload: PluginDocumentSearchPayload): Promise<PluginDocumentResult[]>;
+  getDocument(nodelId: string): Promise<PluginDocumentResult | undefined>;
+  openDocumentEdition(documentId: string, typeName: string): void;
+}
+
+export interface PluginDocumentResult {
+  id: string;
+  title?: string;
+  url?: string;
+  typeName: string;
+  ready?: boolean;
+  publishDate?: string;
+}
+
+export interface PluginDocumentSearchPayload {
+  searchString: string;
+  language?: string;
+  limit?: number;
+  start?: number;
+  orderBy?: OrderByItem[];
+}
+
+export interface AdminUiLogger {
+  error(...messages: any[]): void;
+  warn(...messages: any[]): void;
+  info(...messages: any[]): void;
+  debug(...messages: any[]): void;
+}
+
+export interface AdminUiPluginFieldService extends AdminUiPluginService {
+  fieldType: ScFieldType;
+  setModifiedValue: (value: UpdateFieldValue | (() => UpdateFieldValue)) => void;
+  cancelModifiedValue: () => void;
+  /**
+   * Initial UI language. The admin-ui can update it later using `instance.setLanguage(...)`.
+   */
+  language: string;
+  /**
+   * If the field value is localized (like a text), then it's the content language.
+   */
+  contentLanguage: string;
+  /**
+   * Initial value. The admin-ui can update it later using `instance.setValue(...)`.
+   */
+  initialValue: ReadFieldValue | undefined;
+  uploadMedia?(file: File): Promise<MSourceMedia | undefined>;
+}
+
+export interface PluginDialog {
+  content?: PluginHTMLElement;
+  footer?: PluginHTMLElement;
+  header?: string | PluginHTMLElement;
+  /**
+   * The `handler` is called when the user clicks on the `x` button
+   */
+  onCancel?: () => void;
+}
+
+export type PluginHTMLElement = HTMLElement | false | PluginHTMLElement[];
+
+export interface PluginDialogHandler<T = undefined> {
+  open(): Promise<T | undefined>;
+  close(returnValue?: T): void;
+  show(): void;
+  hide(): void;
+}
+
+export interface AdminUiToastOptions {
+  severity?: "success" | "info" | "warn" | "error" | "secondary";
+}
+
+export interface AdminUiImageVariant {
+  source: MSourceImage;
+  variant: MImageVariant;
+}