@miragon/modeler-shell 0.0.0-stage → 0.1.0

package/src/diagram-js/service.ts

@@ -0,0 +1,240 @@
+import { TEXT_FIELD_SELECTOR, defaultMessages, isUndoRedoKey, matchChromeKey } from "../core/index.js";
+import type { ShellHandle } from "../dom/index.js";
+import { PaletteSkin, type PaletteEntryLike } from "./palette-skin.js";
+import type {
+  CanvasLike,
+  DiagramEventListener,
+  EventBusLike,
+  InjectorLike,
+  KeyboardLike,
+  PaletteLike,
+} from "./types.js";
+
+/** The didi name of the service `shellModule` registers. */
+export const SHELL_SERVICE = "modelerShell";
+
+/** Above `KeyboardBindings` and the modelers' keyboard modules (default priority 1000). */
+export const KEYBOARD_PRIORITY = 2000;
+
+/** Ahead of every default-priority `palette.trigger` listener, so the read-only veto comes first. */
+const TRIGGER_PRIORITY = 2000;
+
+/** A palette without a shell is editable. */
+const EDITABLE = { locked: false, shown: false } as const;
+
+/** What the shell sets on the canvas `<svg>` while a shell is attached, restored on detach. */
+const CANVAS_ATTRIBUTES = ["role", "aria-label"] as const;
+
+function isTextField(target: EventTarget | null): boolean {
+  if (!target || typeof (target as Element).closest !== "function") return false;
+  return (
+    (target as HTMLElement).isContentEditable === true ||
+    (target as Element).closest(TEXT_FIELD_SELECTOR) !== null
+  );
+}
+
+/** didi's injector, which resolves a missing service to `null` with `strict: false`. */
+interface DidiInjectorLike {
+  get(name: string, strict?: boolean): unknown;
+}
+
+interface KeyboardEventContext {
+  keyEvent?: KeyboardEvent;
+}
+
+interface PaletteTriggerEvent {
+  entry?: PaletteEntryLike;
+  event?: Event;
+}
+
+/**
+ * The diagram-side half of `shellModule`: the palette skin, the chrome-key guard on the diagram-js
+ * keyboard and the buffer that holds the palette until `connectDiagramJs` hands it to a shell.
+ */
+export class ShellDiagramService {
+  static $inject = ["eventBus", "injector"];
+
+  private svg: Element | undefined;
+  /** The canvas `<svg>`'s own `role` and `aria-label` before the shell named it. */
+  private canvasOriginals: Map<string, string | null> | undefined;
+  private skin: PaletteSkin | undefined;
+  private activeTool: string | null = null;
+  private shell: ShellHandle | undefined;
+  private unregisterPalette: (() => void) | undefined;
+  private readonly subscriptions: Array<readonly [string, DiagramEventListener]> = [];
+  private destroyed = false;
+
+  constructor(
+    private readonly eventBus: EventBusLike,
+    private readonly injector: DidiInjectorLike,
+  ) {
+    this.subscribe("canvas.init", (event: { svg?: Element }) => {
+      this.svg = event.svg;
+      this.nameCanvas();
+    });
+    this.subscribe("palette.create", (event: { container: HTMLElement }) =>
+      this.onPaletteCreate(event.container),
+    );
+    this.subscribe("palette.changed", () => this.skin?.refresh());
+    this.subscribe("tool-manager.update", (event: { tool?: string | null }) => {
+      this.activeTool = event.tool ?? null;
+      this.skin?.setActiveTool(this.activeTool);
+    });
+    this.subscribe("palette.trigger", this.onPaletteTrigger, TRIGGER_PRIORITY);
+    this.subscribe("diagram.destroy", () => this.destroy());
+
+    const keyboard = injector.get("keyboard", false) as KeyboardLike | null;
+    if (keyboard) {
+      keyboard.addListener(KEYBOARD_PRIORITY, this.onKeyboardKeydown);
+      this.subscriptions.push(["keyboard.keydown", this.onKeyboardKeydown]);
+    }
+  }
+
+  /**
+   * Hands the palette (now or once diagram-js creates it) to `shell`; returns the detach
+   * function. A later call replaces the earlier shell.
+   */
+  attachShell(shell: ShellHandle): () => void {
+    this.detachShell();
+    if (this.destroyed) return () => undefined;
+    this.shell = shell;
+    this.skin?.setLabel(shell.messages.tools);
+    this.nameCanvas();
+    this.registerPalette();
+    return () => {
+      if (this.shell === shell) this.detachShell();
+    };
+  }
+
+  private registerPalette(): void {
+    const { shell, skin } = this;
+    if (!shell || !skin) return;
+    this.unregisterPalette?.();
+    this.unregisterPalette = shell.registerPalette({
+      element: skin.element,
+      entryTooltip: (entry) => skin.entryTooltip(entry),
+      setReadOnly: (state) => skin.setReadOnly(state),
+    });
+  }
+
+  private detachShell(): void {
+    const unregister = this.unregisterPalette;
+    this.unregisterPalette = undefined;
+    this.shell = undefined;
+    unregister?.();
+    this.unnameCanvas();
+    this.skin?.setReadOnly(EDITABLE);
+    this.skin?.setLabel(defaultMessages.tools);
+  }
+
+  /**
+   * The focusable canvas is an application with a name (WCAG 4.1.2): screen readers switch to focus
+   * mode, so the canvas's single-key commands reach it. A role or name the modeler set stays.
+   */
+  private nameCanvas(): void {
+    const { svg, shell } = this;
+    if (!svg || !shell || this.canvasOriginals) return;
+    this.canvasOriginals = new Map(CANVAS_ATTRIBUTES.map((name) => [name, svg.getAttribute(name)]));
+    if (!svg.hasAttribute("role")) svg.setAttribute("role", "application");
+    if (!svg.hasAttribute("aria-label") && !svg.hasAttribute("aria-labelledby")) {
+      svg.setAttribute("aria-label", shell.messages.canvas);
+    }
+  }
+
+  private unnameCanvas(): void {
+    const { svg, canvasOriginals } = this;
+    this.canvasOriginals = undefined;
+    if (!svg || !canvasOriginals) return;
+    for (const [name, value] of canvasOriginals) {
+      if (value === null) svg.removeAttribute(name);
+      else svg.setAttribute(name, value);
+    }
+  }
+
+  private onPaletteCreate(container: HTMLElement): void {
+    this.skin?.destroy();
+    const palette = this.injector.get("palette", false) as PaletteLike | null;
+    const skin = new PaletteSkin(container, () => palette?.getEntries() ?? {});
+    this.skin = skin;
+    skin.setActiveTool(this.activeTool);
+    if (this.shell) skin.setLabel(this.shell.messages.tools);
+    this.moveBeforeCanvas(container);
+    this.registerPalette();
+  }
+
+  // Palette#_init appends the palette after the <svg>; in front of it the palette comes first in
+  // the tab order (guide §5.14).
+  private moveBeforeCanvas(container: HTMLElement): void {
+    const parent = container.parentElement ?? this.canvasContainer();
+    if (!parent) return;
+    const svg =
+      this.svg?.parentNode === parent
+        ? this.svg
+        : Array.from(parent.children).find((child) => child.localName === "svg");
+    if (svg) parent.insertBefore(container, svg);
+  }
+
+  private canvasContainer(): HTMLElement | undefined {
+    const canvas = this.injector.get("canvas", false) as CanvasLike | null;
+    return canvas?.getContainer();
+  }
+
+  private readonly onPaletteTrigger = (event: PaletteTriggerEvent): false | undefined => {
+    if (!event.entry || !this.skin?.vetoes(event.entry, event.event)) return undefined;
+    // A vetoed dragstart would otherwise still start the browser's native drag of the entry.
+    event.event?.preventDefault();
+    return false;
+  };
+
+  /**
+   * `true` stops the diagram-js keyboard (and makes it call `preventDefault`), `false` stops it
+   * without: a chrome key in a text field inside the `<svg>` stays the field's (Shift+1 types "!"),
+   * and in the IDE host undo and redo stay the document's (guide §13.5), so they reach VS Code
+   * instead of the canvas `commandStack`.
+   */
+  private readonly onKeyboardKeydown = (context: KeyboardEventContext): boolean | undefined => {
+    const event = context.keyEvent;
+    if (!event) return undefined;
+    if (matchChromeKey(event)) return !isTextField(event.target);
+    if (this.shell?.host === "ide" && isUndoRedoKey(event)) return false;
+    return undefined;
+  };
+
+  private subscribe<E>(name: string, listener: (event: E) => unknown, priority?: number): void {
+    const handler = listener as DiagramEventListener;
+    if (priority === undefined) this.eventBus.on(name, handler);
+    else this.eventBus.on(name, priority, handler);
+    this.subscriptions.push([name, handler]);
+  }
+
+  private destroy(): void {
+    if (this.destroyed) return;
+    this.destroyed = true;
+    this.detachShell();
+    this.skin?.destroy();
+    this.skin = undefined;
+    this.svg = undefined;
+    for (const [name, listener] of this.subscriptions.splice(0)) this.eventBus.off(name, listener);
+  }
+}
+
+/** The service of `shellModule` in `diagram`; throws when the modeler was built without it. */
+export function shellServiceOf(diagram: InjectorLike): ShellDiagramService {
+  let service: unknown;
+  try {
+    service = diagram.get<unknown>(SHELL_SERVICE);
+  } catch {
+    service = undefined;
+  }
+  if (!isShellService(service)) {
+    throw new Error(
+      "@miragon/modeler-shell: connectDiagramJs needs shellModule in the modeler's modules (additionalModules: [shellModule])",
+    );
+  }
+  return service;
+}
+
+// Duck-typed rather than `instanceof`, so a shellModule from the CJS build connects to the ESM one.
+function isShellService(value: unknown): value is ShellDiagramService {
+  return typeof (value as Partial<ShellDiagramService> | null)?.attachShell === "function";
+}

package/src/diagram-js/types.ts

@@ -0,0 +1,67 @@
+import type { Bounds, Point, ScaledViewbox, Size } from "../core/index.js";
+
+/**
+ * diagram-js services, typed structurally: the shell never imports diagram-js (not even its
+ * types), so it works with every diagram-js 15.28+ build the modeler bundles.
+ */
+
+/** Anything with diagram-js's `get`: a `Diagram`, a renderer's `Modeler`, a didi injector. */
+export interface InjectorLike {
+  get<T>(name: string): T;
+}
+
+/** A didi module declaration, assignable to didi's `ModuleDeclaration`. */
+export interface ModuleDeclarationLike {
+  __init__?: string[];
+  __depends__?: ModuleDeclarationLike[];
+  [name: string]: unknown;
+}
+
+export type DiagramEventListener = (event: never) => unknown;
+
+/** `eventBus` */
+export interface EventBusLike {
+  on(events: string | string[], priority: number, listener: DiagramEventListener): void;
+  on(events: string | string[], listener: DiagramEventListener): void;
+  off(events: string | string[], listener?: DiagramEventListener): void;
+}
+
+/** `canvas.viewbox()` */
+export interface DiagramViewbox extends ScaledViewbox {
+  inner: Bounds;
+  outer: Size;
+}
+
+/** `canvas` */
+export interface CanvasLike {
+  getContainer(): HTMLElement;
+  getSize(): Size;
+  viewbox(): DiagramViewbox;
+  viewbox(box: Bounds): void;
+  zoom(): number;
+  zoom(scale: number, center?: Point): number;
+  resized(): void;
+}
+
+/** `zoomScroll` */
+export interface ZoomScrollLike {
+  stepZoom(delta: number, position?: Point): void;
+}
+
+/** `keyboard` (listeners are removed through `eventBus.off("keyboard.keydown", …)`) */
+export interface KeyboardLike {
+  addListener(priority: number, listener: (context: { keyEvent: KeyboardEvent }) => unknown): void;
+}
+
+/** `palette` */
+export interface PaletteLike {
+  getEntries(): Record<
+    string,
+    {
+      title?: string | undefined;
+      shortcut?: string | undefined;
+      ariaKeyShortcuts?: string | undefined;
+      group?: string | undefined;
+    }
+  >;
+}