@miragon/modeler-shell 0.0.0-stage → 0.1.0

package/src/core/messages.ts

@@ -0,0 +1,88 @@
+/**
+ * Every text the shell shows or announces, in one table (guide §2, shared terms). English by
+ * default; a localized modeler overrides the whole table in its language, numbers arrive already
+ * formatted through `Intl` in that language.
+ */
+export interface ShellMessages {
+  /** Menu trigger `aria-label` and tooltip, dropdown `aria-label`. */
+  menu: string;
+  /** Palette `aria-label`. */
+  tools: string;
+  /** `aria-label` of the focusable canvas `<svg>` (`role="application"`); a modeler names its notation. */
+  canvas: string;
+  /** Zoom panel `aria-label`. */
+  zoom: string;
+  zoomOut: string;
+  zoomIn: string;
+  /** Tooltip of the readout, e.g. `(percent) => "Zoom to " + percent` with percent "100%". */
+  zoomToActual(percent: string): string;
+  /** `aria-label` of the readout: "Zoom to 100% (now 86%)". */
+  zoomToActualNow(percent: string, now: string): string;
+  fit: string;
+  /** Legend title and the Model-group checkbox. */
+  legend: string;
+  closeLegend: string;
+  /** Pill text: "1 problem", "2 problems". */
+  problems(count: number, formattedCount: string): string;
+  /** Pill `aria-label`: "2 problems, 1 error", "2 problems, no errors". */
+  problemsLabel(count: number, errors: number, formattedCount: string, formattedErrors: string): string;
+  /** Pill tooltip in the IDE host. */
+  showProblems: string;
+  /** Empty-file hint (guide §13.5). */
+  emptyHint: string;
+  insertExample: string;
+  /** Status box for an invalid file; `diagram` names the notation ("Event Storming board"). */
+  invalidFile(diagram: string): string;
+  /** Key names in shortcut chips outside macOS (German: Strg, Umschalt, Plus, Minus). */
+  keyNames: { ctrl: string; shift: string; plus: string; minus: string };
+}
+
+/** Every key optional; an `undefined` value keeps the default (a conditional override). */
+export type ShellMessageOverrides = {
+  [Key in Exclude<keyof ShellMessages, "keyNames">]?: ShellMessages[Key] | undefined;
+} & {
+  keyNames?: { [Key in keyof ShellMessages["keyNames"]]?: string | undefined } | undefined;
+};
+
+export const defaultMessages: ShellMessages = {
+  menu: "Menu",
+  tools: "Tools",
+  canvas: "Diagram",
+  zoom: "Zoom",
+  zoomOut: "Zoom out",
+  zoomIn: "Zoom in",
+  zoomToActual: (percent) => `Zoom to ${percent}`,
+  zoomToActualNow: (percent, now) => `Zoom to ${percent} (now ${now})`,
+  fit: "Fit to view",
+  legend: "Legend",
+  closeLegend: "Close legend",
+  problems: (count, formattedCount) => `${formattedCount} ${count === 1 ? "problem" : "problems"}`,
+  problemsLabel: (count, errors, formattedCount, formattedErrors) =>
+    `${formattedCount} ${count === 1 ? "problem" : "problems"}, ${
+      errors === 0 ? "no errors" : `${formattedErrors} ${errors === 1 ? "error" : "errors"}`
+    }`,
+  showProblems: "Show in Problems view",
+  emptyHint: "Pick a tool from the palette to start.",
+  insertExample: "Insert example",
+  invalidFile: (diagram) =>
+    `This file isn't a valid ${diagram} right now. The diagram shows the last valid version and is read-only until you fix the text.`,
+  keyNames: { ctrl: "Ctrl", shift: "Shift", plus: "Plus", minus: "Minus" },
+};
+
+/** `defaultMessages` with `overrides` applied (`keyNames` merged key by key). */
+export function resolveMessages(overrides?: ShellMessageOverrides | undefined): ShellMessages {
+  const { keyNames, ...texts } = overrides ?? {};
+  return {
+    ...defaultMessages,
+    ...definedEntries(texts),
+    keyNames: { ...defaultMessages.keyNames, ...definedEntries(keyNames ?? {}) },
+  };
+}
+
+// `{ menu: undefined }` (a spread of optional fields, a conditional override) keeps the default
+// instead of blanking the text.
+function definedEntries<T extends object>(partial: T): { [Key in keyof T]?: Exclude<T[Key], undefined> } {
+  return Object.fromEntries(Object.entries(partial).filter(([, value]) => value !== undefined)) as {
+    [Key in keyof T]?: Exclude<T[Key], undefined>;
+  };
+}

package/src/core/sizes.ts

@@ -0,0 +1,85 @@
+/**
+ * The shell dimensions of the design system (guide §5.1, `shell` group of
+ * `cd-tokens.generated.json`), keyed by a readable name. Scripts use `SHELL`; CSS uses the
+ * `var(--cd-shell-*)` variables the consumer vendors. A drift test pins `SHELL` to the token JSON.
+ */
+export const SHELL_TOKENS = {
+  edge: "--cd-shell-rand",
+  gap: "--cd-shell-luecke",
+  row: "--cd-shell-zeile",
+  target: "--cd-shell-ziel",
+  entry: "--cd-shell-eintrag",
+  free: "--cd-shell-frei",
+  menuMinWidth: "--cd-shell-menue-breite",
+  inspectorWidth: "--cd-shell-inspector-breite",
+  fitInsetTop: "--cd-shell-einpassen-oben",
+  fitInsetTopSecondRow: "--cd-shell-einpassen-oben-schmal",
+  fitInsetSide: "--cd-shell-einpassen-seite",
+  fitInsetBottom: "--cd-shell-einpassen-unten",
+  fitInsetBottomWeb: "--cd-shell-einpassen-unten-web",
+  narrow: "--cd-shell-schmal",
+  veryNarrow: "--cd-shell-sehr-schmal",
+  low: "--cd-shell-niedrig",
+  layerIslands: "--cd-shell-ebene-inseln",
+  layerInspector: "--cd-shell-ebene-inspector",
+  layerTopRow: "--cd-shell-ebene-reihe",
+  layerPopups: "--cd-shell-ebene-aufklapper",
+  layerDialog: "--cd-shell-ebene-dialog",
+  layerToast: "--cd-shell-ebene-toast",
+} as const;
+
+export type ShellSizeName = keyof typeof SHELL_TOKENS;
+
+export type ShellSizes = Readonly<Record<ShellSizeName, number>>;
+
+/** Pixels (layers: plain z-index numbers), equal to `parseFloat` of the token JSON values. */
+export const SHELL: ShellSizes = {
+  edge: 12,
+  gap: 8,
+  row: 40,
+  target: 32,
+  entry: 36,
+  free: 64,
+  menuMinWidth: 248,
+  inspectorWidth: 288,
+  fitInsetTop: 88,
+  fitInsetTopSecondRow: 140,
+  fitInsetSide: 24,
+  fitInsetBottom: 64,
+  fitInsetBottomWeb: 92,
+  narrow: 760,
+  veryNarrow: 440,
+  low: 820,
+  layerIslands: 20,
+  layerInspector: 25,
+  layerTopRow: 30,
+  layerPopups: 40,
+  layerDialog: 50,
+  layerToast: 60,
+};
+
+// Shell sizes are pixels ("12px") or plain z-index numbers ("20"); any other unit would make
+// parseFloat silently return a number with the wrong meaning.
+const PIXEL_OR_PLAIN_NUMBER = /^\s*-?(?:\d+\.?\d*|\.\d+)(?:px)?\s*$/;
+
+/**
+ * Reads the `shell` group of `cd-tokens.generated.json` (`{ "--cd-shell-rand": "12px", … }`) into
+ * numbers. Throws when a size of `SHELL_TOKENS` is missing or not a number.
+ */
+export function shellSizesFromTokens(shellGroup: Readonly<Record<string, string>>): ShellSizes {
+  const sizes = {} as Record<ShellSizeName, number>;
+  for (const name of Object.keys(SHELL_TOKENS) as ShellSizeName[]) {
+    const token = SHELL_TOKENS[name];
+    const raw: unknown = Object.hasOwn(shellGroup, token) ? shellGroup[token] : undefined;
+    if (raw === undefined) {
+      throw new Error(`@miragon/modeler-shell: the shell token ${token} is missing`);
+    }
+    if (typeof raw !== "string" || !PIXEL_OR_PLAIN_NUMBER.test(raw)) {
+      throw new Error(
+        `@miragon/modeler-shell: the shell token ${token} is not a number: ${JSON.stringify(raw)}`,
+      );
+    }
+    sizes[name] = Number.parseFloat(raw);
+  }
+  return sizes;
+}

package/src/core/types.ts

@@ -0,0 +1,84 @@
+/** A point in pixels or diagram coordinates, as the context says. */
+export interface Point {
+  x: number;
+  y: number;
+}
+
+export interface Size {
+  width: number;
+  height: number;
+}
+
+/** A rectangle; content bounds and viewboxes are in diagram coordinates. */
+export interface Bounds {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+/** A viewbox together with the scale diagram-js shows it at (`canvas.viewbox().scale`). */
+export interface ScaledViewbox extends Bounds {
+  scale: number;
+}
+
+/** Distances in pixels from the edges of the modeler's container. */
+export interface Insets {
+  top: number;
+  right: number;
+  bottom: number;
+  left: number;
+}
+
+/**
+ * The host column of guide §5.2: `ide` is a VS Code webview (later IntelliJ), `web` a Miragon web
+ * app that owns its page, `embedded` a modeler inside a foreign page (designIQ, modeler-api hosts).
+ */
+export type ShellHost = "ide" | "web" | "embedded";
+
+/** The `data-chrome` names of the islands (guide §5.2, §13.4). `primary` is reserved for the web app. */
+export type ChromeIsland =
+  "menu" | "palette" | "primary" | "zoom" | "problems" | "legend" | "inspector" | "status";
+
+export const CHROME_ISLANDS: readonly ChromeIsland[] = [
+  "menu",
+  "palette",
+  "primary",
+  "zoom",
+  "problems",
+  "legend",
+  "inspector",
+  "status",
+];
+
+/** Where the palette sits: in the top row, or in the second row below it (guide §5.15). */
+export type PaletteRow = "top" | "second-row";
+
+/**
+ * What the zoom panel and the chrome keys act on. The diagram-js viewport implements it; the DOM
+ * shell only talks to this interface.
+ */
+export interface ZoomTarget {
+  /** The current zoom, 1 = 100 % (diagram-js `canvas.zoom()`, rounded to three decimals). */
+  zoom(): number;
+  /** One step on the zoom raster around the container centre (diagram-js `zoomScroll.stepZoom`). */
+  stepZoom(direction: 1 | -1): void;
+  /** 100 % around the container centre. Counts as a user move. */
+  zoomToActual(): void;
+  /** Explicit fit (button, Shift+1, command): animated unless reduced motion, makes the view automatic. */
+  fit(): void;
+  /** False while there is nothing to fit (the content bounds are empty). */
+  canFit(): boolean;
+  /**
+   * Calls `listener` after every viewbox change and whenever `canFit()` may have changed, possibly
+   * several times per frame. Returns the unsubscribe function.
+   */
+  onChange(listener: () => void): () => void;
+}
+
+/** The persisted view (VS Code `setState`): JSON-serializable. */
+export interface ViewportState {
+  viewbox: Bounds;
+  /** The user zoomed or panned since the last fit; a resize no longer refits. */
+  userMoved: boolean;
+}

package/src/core/zoom.ts

@@ -0,0 +1,74 @@
+import type { ShellMessages } from "./messages.js";
+
+/** diagram-js `ZoomScroll` RANGE (not configurable): 20 % … 400 %. */
+export const ZOOM_MIN = 0.2;
+export const ZOOM_MAX = 4;
+
+/** Zoom out is disabled at 20 % and below (`zoom <= 0.2 · 1.001`), so it never zooms in. */
+export function canZoomOut(zoom: number): boolean {
+  return zoom > ZOOM_MIN * 1.001;
+}
+
+/** Zoom in is disabled at 400 % (`zoom >= 4 · 0.999`). */
+export function canZoomIn(zoom: number): boolean {
+  return zoom < ZOOM_MAX * 0.999;
+}
+
+/**
+ * A zoom as a whole percentage in the UI language: `Intl.NumberFormat(lang, { style: "percent",
+ * maximumFractionDigits: 0 })`, so English "86%", German "86 %" (with U+00A0).
+ */
+export function formatPercent(zoom: number, lang: string): string {
+  return numberFormat(lang, "percent").format(zoom);
+}
+
+/** Any other number in the chrome ("2 problems"), via `Intl.NumberFormat(lang)`. */
+export function formatNumber(value: number, lang: string): string {
+  return numberFormat(lang, "decimal").format(value);
+}
+
+const FALLBACK_LANG = "en";
+const formats = new Map<string, Intl.NumberFormat>();
+
+// The readout formats on every animation frame of a zoom, so each formatter is built once. A
+// language tag Intl rejects (an empty `lang=""`, a typo) falls back to English, the shell's default
+// language, instead of breaking the chrome.
+function numberFormat(lang: string, style: "percent" | "decimal"): Intl.NumberFormat {
+  const key = `${style}|${lang}`;
+  let format = formats.get(key);
+  if (!format) {
+    const options: Intl.NumberFormatOptions =
+      style === "percent" ? { style, maximumFractionDigits: 0 } : { style };
+    try {
+      format = new Intl.NumberFormat(lang, options);
+    } catch {
+      format = new Intl.NumberFormat(FALLBACK_LANG, options);
+    }
+    formats.set(key, format);
+  }
+  return format;
+}
+
+export interface ZoomReadout {
+  /** "86%" */
+  text: string;
+  /** "Zoom to 100% (now 86%)" */
+  ariaLabel: string;
+  canZoomOut: boolean;
+  canZoomIn: boolean;
+}
+
+/** Everything the zoom panel shows for a zoom: readout text, its accessible name and the limits. */
+export function zoomReadout(
+  zoom: number,
+  lang: string,
+  messages: Pick<ShellMessages, "zoomToActualNow">,
+): ZoomReadout {
+  const text = formatPercent(zoom, lang);
+  return {
+    text,
+    ariaLabel: messages.zoomToActualNow(formatPercent(1, lang), text),
+    canZoomOut: canZoomOut(zoom),
+    canZoomIn: canZoomIn(zoom),
+  };
+}

package/src/core.ts

@@ -0,0 +1,2 @@
+// "@miragon/modeler-shell/core": DOM-free (Node, extension host, workers, unit tests).
+export * from "./core/index.js";

package/src/diagram-js/connect.ts

@@ -0,0 +1,75 @@
+import type { Bounds } from "../core/index.js";
+import type { ShellHandle } from "../dom/index.js";
+import { shellServiceOf } from "./service.js";
+import type { DiagramEventListener, EventBusLike, InjectorLike } from "./types.js";
+import { DiagramViewport, type Viewport } from "./viewport.js";
+
+export interface ConnectOptions {
+  /**
+   * Content bounds in diagram coordinates, tight around the content: the fit insets are the only
+   * margin (guide §5.9). `undefined` = nothing to fit (empty file).
+   */
+  contentBounds(): Bounds | undefined;
+  /**
+   * An empty file (guide §13.5: no element, only whitespace, comments or a title), which shows the
+   * empty-file hint. Default: `contentBounds()` is empty. A notation whose bounds are never empty
+   * (Wardley's plot) passes its own test.
+   */
+  isEmpty?: (() => boolean) | undefined;
+  prefersReducedMotion?: (() => boolean) | undefined;
+}
+
+export interface DiagramJsConnection {
+  readonly viewport: Viewport;
+  /**
+   * Unbinds viewport, palette, keys and the hint sync from the shell; destroys neither the diagram
+   * nor the shell. Runs by itself on `diagram.destroy`.
+   */
+  destroy(): void;
+}
+
+/** After the viewport's own listeners, so its content state is fresh when the hint reads it. */
+const HINT_SYNC_PRIORITY = 500;
+
+/**
+ * Connects a diagram built with `shellModule` to a mounted shell: creates the viewport with
+ * `shell.fitInsets`, binds it with `shell.setZoomTarget`, registers the palette
+ * (`shell.registerPalette`), keeps the empty-file hint in sync with the diagram (after every
+ * `import.done` and `elements.changed`, so the first element created on the canvas hides it) and
+ * calls `canvas.resized()`. Throws when `shellModule` is missing.
+ */
+export function connectDiagramJs(
+  shell: ShellHandle,
+  diagram: InjectorLike,
+  options: ConnectOptions,
+): DiagramJsConnection {
+  const service = shellServiceOf(diagram);
+  const eventBus = diagram.get<EventBusLike>("eventBus");
+  const prefersReducedMotion = options.prefersReducedMotion?.bind(options);
+  const viewport = new DiagramViewport(diagram, {
+    contentBounds: () => options.contentBounds(),
+    insets: () => shell.fitInsets(),
+    ...(prefersReducedMotion ? { prefersReducedMotion } : {}),
+  });
+  shell.setZoomTarget(viewport);
+  const detachPalette = service.attachShell(shell);
+  // The shell has moved the canvas element into its slot; diagram-js caches the old size.
+  viewport.resized();
+
+  const isEmpty = options.isEmpty ? () => options.isEmpty?.() === true : () => !viewport.canFit();
+  const syncHint: DiagramEventListener = () => shell.setEmptyHint(isEmpty());
+  eventBus.on(["import.done", "elements.changed"], HINT_SYNC_PRIORITY, syncHint);
+
+  let destroyed = false;
+  const destroy = (): void => {
+    if (destroyed) return;
+    destroyed = true;
+    eventBus.off(["import.done", "elements.changed"], syncHint);
+    eventBus.off("diagram.destroy", destroy);
+    detachPalette();
+    shell.setZoomTarget(null);
+    viewport.destroy();
+  };
+  eventBus.on("diagram.destroy", destroy);
+  return { viewport, destroy };
+}

package/src/diagram-js/index.ts

@@ -0,0 +1,16 @@
+export type {
+  CanvasLike,
+  DiagramEventListener,
+  DiagramViewbox,
+  EventBusLike,
+  InjectorLike,
+  KeyboardLike,
+  ModuleDeclarationLike,
+  PaletteLike,
+  ZoomScrollLike,
+} from "./types.js";
+export { shellModule } from "./module.js";
+export type { Viewport, ViewportOptions } from "./viewport.js";
+export { createViewport } from "./viewport.js";
+export type { ConnectOptions, DiagramJsConnection } from "./connect.js";
+export { connectDiagramJs } from "./connect.js";

package/src/diagram-js/module.ts

@@ -0,0 +1,20 @@
+import { SHELL_SERVICE, ShellDiagramService } from "./service.js";
+import type { ModuleDeclarationLike } from "./types.js";
+
+/**
+ * Add to the modeler's modules (`additionalModules`, after the renderer's own modules):
+ * - `paletteTooltip: ["value", null]` removes diagram-js's (or the renderer's) palette tooltip; the
+ *   chrome tooltip takes over;
+ * - the palette skin: on `palette.create` it sets `data-chrome="palette"` and moves the palette
+ *   before the canvas `<svg>`; after every `palette.changed` it re-applies `role="toolbar"`,
+ *   `aria-label`, roving `tabindex` and `aria-pressed` (from `tool-manager.update`);
+ * - `keyboard.addListener(2000, …)` returning `true` for every chrome key, so `KeyboardBindings` and
+ *   the modeler's keyboard modules (priority 1000) never act on them.
+ * It buffers the palette until `connectDiagramJs` hands it to a shell, so the diagram may be
+ * constructed before `mountShell`.
+ */
+export const shellModule: ModuleDeclarationLike = {
+  __init__: [SHELL_SERVICE],
+  [SHELL_SERVICE]: ["type", ShellDiagramService],
+  paletteTooltip: ["value", null],
+};