@miragon/modeler-shell 0.1.0 → 0.2.0

package/src/dom/types.ts

@@ -1,10 +1,14 @@
 import type {
+  AppearanceChoice,
   Insets,
   Platform,
+  ProblemItem,
   ShellHost,
   ShellMessageOverrides,
   ShellMessages,
   Theme,
+  ThemeColors,
+  ToastRequest,
   ZoomTarget,
 } from "../core/index.js";
 import type { ShellIconName } from "./icons.js";
@@ -32,10 +36,11 @@ export interface ShellOptions {
   keyScope?: "document" | "root" | undefined;
   /**
    * The modes the modeler can show (a static value of the modeler package), default `["light"]`.
-   * Read in the `embedded` host only: there the root carries `data-cd-theme="<themes[0]>"` itself
-   * (until the contract's `appearance` surface an embedded modeler stays in its first mode,
-   * whatever the page shows) and mirrors the host's `data-cd-kontrast` (guide §13.3). In an own
-   * document the host writes the mode on `<html>`.
+   * Read in the `embedded` and `web` hosts. Embedded: the root carries `data-cd-theme="<themes[0]>"`
+   * itself (until the contract's `appearance` surface an embedded modeler stays in its first mode,
+   * whatever the page shows) and mirrors the host's `data-cd-kontrast` (guide §13.3). Web: with
+   * `"dark"` the shell renders the Appearance group and applies the choice on `<html>` (needs
+   * `appearance`); light-only it renders no group. In the `ide` host the host writes the mode.
    */
   themes?: readonly Theme[] | undefined;
   /** The fixed menu groups this modeler fills (guide §5.4); omitted groups and empty ones collapse. */
@@ -48,6 +53,24 @@ export interface ShellOptions {
   inspector?: InspectorOptions | undefined;
   /** The empty-file hint of IDE and embedded hosts (guide §13.5); omitted = no hint. */
   emptyHint?: EmptyHintOptions | undefined;
+
+  // ---- Web host (0.2): read in `host: "web"` only, ignored elsewhere (guide §5.2) ----
+
+  /** The primary action at the top right (guide §5.7); omitted = the top right stays empty. */
+  primary?: PrimaryActionOptions | undefined;
+  /**
+   * The legal line at the bottom left (guide §5.10), always rendered in the web host: copyright,
+   * Impressum and Datenschutz (`lang="de"`), then `links`.
+   */
+  legal?: LegalLineOptions | undefined;
+  /** The File group, first in the menu (guide §5.4); omitted = no File group. */
+  file?: FileMenuOptions | undefined;
+  /** The mode choice of a dark-capable modeler (guide §13.3); required when `themes` includes `"dark"`. */
+  appearance?: WebAppearanceOptions | undefined;
+  /** The start screen (guide §8 Empty State); omitted = none. Shown by `setEmptyState(true)`. */
+  emptyState?: EmptyStateOptions | undefined;
+  /** Files dropped anywhere on the page (guide §9 Drag-over, Drop forbidden); omitted = none. */
+  dropZone?: DropZoneOptions | undefined;
 }
 
 /** Rendered in this order, separated by separators: Model, Export, Help (guide §5.4). */
@@ -96,6 +119,10 @@ export interface MenuActionEntry extends MenuItemBase {
  */
 export interface MenuDialogEntry extends MenuItemBase {
   kind: "dialog";
+  /** Shortcut chip text shown on the right, verbatim ("?" for "Keyboard shortcuts…"). */
+  shortcut?: string | undefined;
+  /** As for `MenuActionEntry`: default `ariaKeyShortcutsFromLabel(shortcut)`, `""` sets none. */
+  ariaKeyShortcuts?: string | undefined;
   onSelect(): void;
 }
 
@@ -126,8 +153,17 @@ export interface MenuRadioOption {
 }
 
 export interface ProblemsOptions {
-  /** A click on the pill: the IDE host opens its Problems view. */
-  onActivate(): void;
+  /**
+   * A click on the pill where the host has a problems view of its own: the IDE host opens its
+   * Problems view (give it there), an embedding host its own list. Ignored in the web host, where
+   * the pill opens the problems popover; an embedded shell without it opens the popover as well.
+   */
+  onActivate?: (() => void) | undefined;
+  /**
+   * A click on a row of the problems popover, after the popover closed (guide §5.10): select the
+   * element the item names, where there is one.
+   */
+  onSelectItem?: ((item: ProblemItem) => void) | undefined;
 }
 
 export interface LegendOptions {
@@ -168,6 +204,10 @@ export interface ShellHandle {
   readonly tooltip: TooltipHandle;
   readonly legend: LegendHandle | undefined;
   readonly inspector: InspectorHandle | undefined;
+  /** The web app's primary action; `undefined` without `primary` and outside the web host. */
+  readonly primary: PrimaryActionHandle | undefined;
+  /** The web app's mode choice; `undefined` outside the web host and for a light-only modeler. */
+  readonly appearance: AppearanceHandle | undefined;
   /** Binds zoom panel, readout and chrome keys; `null` unbinds (buttons disabled). */
   setZoomTarget(target: ZoomTarget | null): void;
   /** The fit insets for what is open right now (palette row, legend, inspector, pill). */
@@ -194,6 +234,21 @@ export interface ShellHandle {
   setReadOnly(readOnly: boolean, options?: { delayMs?: number | undefined }): void;
   /** The lock, true from the first `setReadOnly(true)` on, also while its marks are still delayed. */
   isReadOnly(): boolean;
+  /**
+   * Shows or hides the web app's start screen (guide §8): while it shows, menu trigger, primary
+   * action, palette, zoom panel, pill, legend, status box, hint and inspector are hidden, the canvas
+   * slot is `inert` and the chrome keys do nothing; the legal line, toasts and the drop zone stay.
+   * A no-op without `emptyState`. Hiding it while it holds the focus moves the focus to the canvas.
+   */
+  setEmptyState(shown: boolean): void;
+  isEmptyStateShown(): boolean;
+  /**
+   * Shows a toast (guide §8, §9) in the web and embedded hosts: bottom centre, at most three, the
+   * newest at the bottom, closing by itself after `toastLifetime` unless hovered or focused. In the
+   * `ide` host it shows nothing and returns an inert handle: there the extension shows the host's
+   * notification (§13.5).
+   */
+  toast(request: ToastRequest): ToastHandle;
   /** Removes every element, attribute, listener, observer and timer the shell added. Idempotent. */
   destroy(): void;
 }
@@ -267,6 +322,11 @@ export interface ProblemSummary {
   count: number;
   /** How many of them are errors; decides icon and wording. */
   errors: number;
+  /**
+   * The rows of the problems popover (web, embedded without `onActivate`), in this order; the IDE
+   * host ignores them. `problemSummary(items)` builds the whole summary from them.
+   */
+  items?: readonly ProblemItem[] | undefined;
 }
 
 export type StatusSeverity = "danger" | "warning";
@@ -275,3 +335,125 @@ export interface StatusMessage {
   severity: StatusSeverity;
   text: string;
 }
+
+// ---- Web host (0.2) ----
+
+/** The web app's primary action (guide §5.7): a blue primary button, icon and label, at the top right. */
+export interface PrimaryActionOptions {
+  /** Label and `aria-label`; default `messages.share` ("Share"). */
+  label?: string | undefined;
+  /** Default `"share-2"`. */
+  icon?: ShellIconName | undefined;
+  onSelect(): void;
+  /** Read on mount and on `primary.refresh()`; disabled stays focusable (`aria-disabled`). */
+  disabled?: (() => boolean) | undefined;
+}
+
+export interface PrimaryActionHandle {
+  /** The `<button data-chrome="primary">`. */
+  readonly element: HTMLButtonElement;
+  /** True while the label is collapsed to the icon (guide §5.15); the root then carries `data-primary="collapsed"`. */
+  isCollapsed(): boolean;
+  /** Re-reads `disabled()`. */
+  refresh(): void;
+}
+
+/** A link of the legal line after Impressum and Datenschutz. */
+export interface LegalLink {
+  label: string;
+  href: string;
+  /** For a label in another language than the tool's. */
+  lang?: string | undefined;
+}
+
+export interface LegalLineOptions {
+  /** After Impressum and Datenschutz: `{ label: "GitHub", href: "https://github.com/Miragon/…" }`. */
+  links?: readonly LegalLink[] | undefined;
+  /** The copyright year; default the current year at mount. */
+  year?: number | undefined;
+}
+
+/** One entry of the File group; label and icon come from the shell (guide §2, §5.4). */
+export interface FileMenuAction {
+  onSelect(): void;
+  /** Shortcut chip, e.g. "⌘O"; the web app binds the key itself. */
+  shortcut?: string | undefined;
+  /** `kind: "dialog"` (`aria-haspopup="dialog"`) when it opens an in-page dialog, not the browser's file picker. */
+  dialog?: boolean | undefined;
+  disabled?: (() => boolean) | undefined;
+}
+
+/**
+ * The File group of the web app (guide §5.4), in this order, as far as the modeler has them:
+ * "New diagram" (`file-plus`), "Open…" (`folder-open`), "Show example", "Import…" (`import`).
+ * Menu ids `new-diagram`, `open`, `show-example`, `import`, `data-menu-group="file"`.
+ */
+export interface FileMenuOptions {
+  newDiagram?: FileMenuAction | undefined;
+  open?: FileMenuAction | undefined;
+  showExample?: FileMenuAction | undefined;
+  import?: FileMenuAction | undefined;
+}
+
+/** What `localStorage` offers; a blocked storage throws, the shell catches it. */
+export interface StorageLike {
+  getItem(key: string): string | null;
+  setItem(key: string, value: string): void;
+  removeItem(key: string): void;
+}
+
+export interface WebAppearanceOptions {
+  /** The two `theme-color` values from the vendored token JSON (see `ThemeColors`). */
+  themeColors: ThemeColors;
+  /** Default `globalThis.localStorage`. */
+  storage?: StorageLike | undefined;
+}
+
+/** The mode choice of a dark-capable web app (guide §13.3), as the Appearance group drives it. */
+export interface AppearanceHandle {
+  /** The stored choice, `"system"` without one. */
+  choice(): AppearanceChoice;
+  /**
+   * Stores the choice (`"system"` removes `APPEARANCE_STORAGE_KEY`) and applies `documentMode` on
+   * `<html>` and the metas in one step, with `cd-shell-no-transition` for one frame (guide §7).
+   */
+  setChoice(choice: AppearanceChoice): void;
+}
+
+/** The web app's start screen (guide §8): a centred glass card with the Komet and two actions. */
+export interface EmptyStateOptions {
+  /** The card's title (h1, 21px/600), the modeler's name: "Event Storming Modeler". */
+  title: string;
+  /** One line of help (16px/1.6, `--cd-ui-text-leise`): "Start a new diagram, or explore the example." */
+  text: string;
+  /**
+   * URL of the official Miragon icon `miragon-komet-blau.svg`, vendored unchanged from
+   * `Miragon/corporate-identity` (guide §2, §11), shown at 64px with `alt=""`.
+   */
+  komet: string;
+  /** "New diagram", the blue primary button. The shell hides the card first. */
+  onNewDiagram(): void;
+  /** "Show example", the ghost button; omitted = no example button. The shell hides the card first. */
+  onShowExample?: (() => void) | undefined;
+  /** The drag-and-drop hint (13px, `--cd-ui-text-leise`), shown with a `dropZone` only; default `messages.dropHint`. */
+  dropHint?: string | undefined;
+}
+
+export interface DropZoneOptions {
+  /**
+   * Like `<input accept>`: extensions (".storm") and MIME types ("application/json", "text/*").
+   * List the MIME types too, so a drag can already show a foreign type as forbidden. Empty = any file.
+   */
+  accept: readonly string[];
+  /** Default `false`: a drag with more than one file is forbidden. */
+  multiple?: boolean | undefined;
+  /** The dropped files that match `accept` (one unless `multiple`). */
+  onDrop(files: readonly File[]): void;
+  /** The dropped files outside `accept`; default a danger toast `messages.cannotOpenFile`. */
+  onReject?: ((files: readonly File[]) => void) | undefined;
+}
+
+export interface ToastHandle {
+  /** Closes the toast (slide and fade out); a second call does nothing. */
+  dismiss(): void;
+}

package/src/dom/web/drop-zone.ts

@@ -0,0 +1,181 @@
+import {
+  acceptsFile,
+  dragVerdict,
+  type DragItemLike,
+  type DragVerdict,
+  type ShellMessages,
+  type ToastRequest,
+} from "../../core/index.js";
+import { createElement } from "../element.js";
+import type { DropZoneOptions, ToastHandle } from "../types.js";
+
+/** The drop zone as the root shows it: `data-drop="over"` or `"forbidden"` while a file drag is on the page. */
+export type DropZoneState = "over" | "forbidden" | null;
+
+export interface DropZoneContext {
+  ownerDocument: Document;
+  /** Where the overlay goes: the shell's layer (40, guide §5.13). */
+  layer: HTMLElement;
+  messages: ShellMessages;
+  lang: string;
+  options: DropZoneOptions;
+  /** A modal dialog is open in the document (the shell's dialog test). */
+  modalOpen(): boolean;
+  /** For the default `onReject`. */
+  toast(request: ToastRequest): ToastHandle;
+  /** Writes the root's `data-drop`. */
+  setState(state: DropZoneState): void;
+}
+
+export interface DropZoneController {
+  /** The overlay `<div data-chrome="drop-zone" aria-hidden="true">`. */
+  readonly element: HTMLElement;
+  state(): DropZoneState;
+  destroy(): void;
+}
+
+const DRAG_EVENTS = ["dragenter", "dragover", "dragleave", "drop"] as const;
+
+function carriesFiles(transfer: DataTransfer | null): transfer is DataTransfer {
+  if (!transfer) return false;
+  if (Array.from(transfer.types ?? []).includes("Files")) return true;
+  return Array.from(transfer.items ?? []).some((item) => item.kind === "file");
+}
+
+/** What the drag shows of its items; a browser without `items` still names "Files" in `types`. */
+function dragItems(transfer: DataTransfer): DragItemLike[] {
+  const items = Array.from(transfer.items ?? [], (item) => ({ kind: item.kind, type: item.type }));
+  return items.length > 0 ? items : [{ kind: "file", type: "" }];
+}
+
+/** The extensions of `accept` for the reject toast ("a .storm, .json, or .txt file"), else every entry. */
+function acceptList(accept: readonly string[], lang: string): string {
+  const entries = accept.map((entry) => entry.trim()).filter((entry) => entry !== "");
+  const extensions = entries.filter((entry) => entry.startsWith("."));
+  const listed = extensions.length > 0 ? extensions : entries;
+  let format: Intl.ListFormat;
+  try {
+    format = new Intl.ListFormat(lang, { type: "disjunction" });
+  } catch {
+    format = new Intl.ListFormat("en", { type: "disjunction" });
+  }
+  return format.format(listed);
+}
+
+/**
+ * The page-wide drop zone of the web app (guide §9). Listens on the window (`dragenter`,
+ * `dragover`, `dragleave`, `drop`; outermost pair counted) for drags carrying files only, so
+ * palette drags and text drags into the label editor stay alone; `dragVerdict` decides the state.
+ * Drag-over: overlay `inset: 12px`, fill `--cd-ui-hover`, 2px dashed `--cd-ui-interaktion`, radius
+ * `lg`, chip `messages.dropFile` centred on `--cd-ui-flaeche-hoch` (13px/600, radius `md`,
+ * `shadow-2`), `dropEffect = "copy"`. Forbidden: fill `--cd-ui-danger-flaeche`, dashed
+ * `--cd-ui-danger`, chip `messages.dropForbidden(reason)`, `dropEffect = "none"` (cursor
+ * `not-allowed`). Every file drag is `preventDefault`-ed, so the browser never navigates to the
+ * file. A drop: files through `acceptsFile` → `onDrop(accepted)`, the rest → `onReject` (default
+ * a danger toast `cannotOpenFile(name, accept joined by Intl.ListFormat disjunction)`); a forbidden
+ * drop opens nothing. Hidden while no file drag is on the page.
+ */
+export function createDropZone(context: DropZoneContext): DropZoneController {
+  const { ownerDocument, layer, messages, lang, options, modalOpen, toast, setState } = context;
+  const chip = createElement(ownerDocument, "span", { class: "cd-shell-drop-zone-chip" });
+  const element = createElement(
+    ownerDocument,
+    "div",
+    { class: "cd-shell-drop-zone", "data-chrome": "drop-zone", "aria-hidden": "true" },
+    chip,
+  );
+  element.hidden = true;
+  layer.append(element);
+
+  const view = ownerDocument.defaultView;
+  // dragenter and dragleave fire for every element the pointer crosses: only the outermost pair counts.
+  let depth = 0;
+  let current: DropZoneState = null;
+
+  function verdictFor(items: readonly DragItemLike[]): DragVerdict {
+    return dragVerdict(items, {
+      accept: options.accept,
+      multiple: options.multiple ?? false,
+      dialogOpen: modalOpen(),
+    });
+  }
+
+  function show(verdict: DragVerdict): void {
+    const next: DropZoneState = verdict.state === "none" ? null : verdict.state;
+    if (verdict.state === "over") chip.textContent = messages.dropFile;
+    if (verdict.state === "forbidden") chip.textContent = messages.dropForbidden(verdict.reason);
+    if (next === current) return;
+    current = next;
+    element.hidden = next === null;
+    if (next === null) element.removeAttribute("data-state");
+    else element.setAttribute("data-state", next);
+    setState(next);
+  }
+
+  function track(transfer: DataTransfer): void {
+    const verdict = verdictFor(dragItems(transfer));
+    show(verdict);
+    transfer.dropEffect = verdict.state === "forbidden" ? "none" : "copy";
+  }
+
+  function rejectByDefault(files: readonly File[]): void {
+    const accepted = acceptList(options.accept, lang);
+    for (const file of files) toast({ status: "danger", text: messages.cannotOpenFile(file.name, accepted) });
+  }
+
+  function receive(files: readonly File[], verdict: DragVerdict): void {
+    // The type verdict only guesses while names are unreadable; at the drop acceptsFile knows.
+    if (verdict.state === "forbidden" && verdict.reason !== "type") return;
+    const accepted = files.filter((file) => acceptsFile(file, options.accept));
+    const rejected = files.filter((file) => !accepted.includes(file));
+    if (accepted.length > 0) options.onDrop(accepted);
+    if (rejected.length > 0) (options.onReject ?? rejectByDefault)(rejected);
+  }
+
+  const onDragEvent = (event: Event): void => {
+    const transfer = (event as DragEvent).dataTransfer;
+    if (!carriesFiles(transfer)) return;
+    // Unprevented, the browser opens the file in place of the app.
+    event.preventDefault();
+    switch (event.type) {
+      case "dragenter":
+        depth += 1;
+        track(transfer);
+        break;
+      case "dragover":
+        // A drag that entered before the listener existed is on the page all the same.
+        depth = Math.max(depth, 1);
+        track(transfer);
+        break;
+      case "dragleave":
+        depth = Math.max(0, depth - 1);
+        if (depth === 0) show({ state: "none" });
+        break;
+      case "drop": {
+        depth = 0;
+        show({ state: "none" });
+        const files = Array.from(transfer.files ?? []);
+        const items =
+          files.length > 0 ? files.map((file) => ({ kind: "file", type: file.type })) : dragItems(transfer);
+        receive(files, verdictFor(items));
+        break;
+      }
+    }
+  };
+
+  for (const type of DRAG_EVENTS) view?.addEventListener(type, onDragEvent);
+
+  return {
+    element,
+    state: () => current,
+    destroy() {
+      for (const type of DRAG_EVENTS) view?.removeEventListener(type, onDragEvent);
+      depth = 0;
+      if (current !== null) {
+        current = null;
+        setState(null);
+      }
+      element.remove();
+    },
+  };
+}

package/src/dom/web/empty-state.ts

@@ -0,0 +1,144 @@
+import { ariaKeyShortcutsFromLabel, type ShellMessages } from "../../core/index.js";
+import { createElement } from "../element.js";
+import type { EmptyStateOptions, FileMenuAction } from "../types.js";
+
+export interface EmptyStateContext {
+  ownerDocument: Document;
+  messages: ShellMessages;
+  options: EmptyStateOptions;
+  /** The drop hint under the buttons; `undefined` without a drop zone. */
+  dropHint: string | undefined;
+  /**
+   * The File group's "Open…": the hint offers it as a text link, the keyboard's way to a file
+   * while the start screen hides the menu and a drop needs a pointer. `undefined` without one.
+   */
+  open?: FileMenuAction | undefined;
+  /** `id` of the title, the section's `aria-labelledby`. */
+  titleId: string;
+  /** Runs before `onNewDiagram` / `onShowExample`: the shell hides the card and moves the focus. */
+  onLeave(): void;
+}
+
+export interface EmptyStateController {
+  /** The `<section data-chrome="empty-state">`. */
+  readonly element: HTMLElement;
+  isShown(): boolean;
+  setShown(shown: boolean): void;
+  /** Focuses "New diagram", the card's first button. */
+  focus(): void;
+  destroy(): void;
+}
+
+/** The Komet's size on the card (guide §8). */
+const KOMET_SIZE = "64";
+
+/**
+ * `<section class="cd-shell-empty-state" data-chrome="empty-state" aria-labelledby>` (guide §8):
+ * centred in the container, `min(400px, 100cqw − 24px)` wide, glass, `shadow-2`, radius `lg`,
+ * padding `32px 40px`, content centred with 16px gaps: `<img src=komet width=64 height=64
+ * alt="">`, `<h1>` title 21px/600, help 16px/1.6 `--cd-ui-text-leise`, then the buttons side by
+ * side with 8px gap, 36px high (`cd-shell-button`): primary "New diagram" first, ghost "Show
+ * example", then the drop hint 13px `--cd-ui-text-leise`. With the File group's "Open…" the hint
+ * ends in a text link `messages.openFileLink` in `--cd-ui-link` (and its shortcut chip in Geist
+ * Mono): not a third action, the keyboard's way to open a file. Opening keeps the card until the
+ * modeler leaves it (`setEmptyState(false)` after the file loaded). Layer 20, `hidden` until
+ * `setShown(true)`.
+ */
+export function createEmptyState(context: EmptyStateContext): EmptyStateController {
+  const { ownerDocument, messages, options, dropHint, open, titleId, onLeave } = context;
+
+  const button = (variant: "primary" | "ghost", label: string, run: () => void): HTMLButtonElement => {
+    const element = createElement(
+      ownerDocument,
+      "button",
+      { type: "button", class: "cd-shell-button", "data-variant": variant },
+      label,
+    );
+    element.addEventListener("click", () => {
+      onLeave();
+      run();
+    });
+    return element;
+  };
+
+  const onShowExample = options.onShowExample;
+  const newDiagram = button("primary", messages.newDiagram, () => options.onNewDiagram());
+  const element = createElement(
+    ownerDocument,
+    "section",
+    { class: "cd-shell-empty-state", "data-chrome": "empty-state", "aria-labelledby": titleId },
+    // Dragging the mark would start an image drag that some browsers carry as a file.
+    createElement(ownerDocument, "img", {
+      class: "cd-shell-empty-state-mark",
+      src: options.komet,
+      width: KOMET_SIZE,
+      height: KOMET_SIZE,
+      alt: "",
+      draggable: "false",
+    }),
+    createElement(ownerDocument, "h1", { class: "cd-shell-empty-state-title", id: titleId }, options.title),
+    createElement(ownerDocument, "p", { class: "cd-shell-empty-state-text" }, options.text),
+    createElement(
+      ownerDocument,
+      "div",
+      { class: "cd-shell-empty-state-actions" },
+      newDiagram,
+      onShowExample && button("ghost", messages.showExample, () => onShowExample()),
+    ),
+    hintParagraph(),
+  );
+
+  function hintParagraph(): HTMLElement | undefined {
+    const hasDropHint = dropHint !== undefined && dropHint !== "";
+    if (!hasDropHint && !open) return undefined;
+    const paragraph = createElement(ownerDocument, "p", { class: "cd-shell-empty-state-hint" });
+    if (hasDropHint) paragraph.append(dropHint);
+    if (!open) return paragraph;
+    const shortcut = open.shortcut?.trim();
+    const link = createElement(
+      ownerDocument,
+      "button",
+      {
+        type: "button",
+        class: "cd-shell-empty-state-open",
+        "aria-keyshortcuts": shortcut ? ariaKeyShortcutsFromLabel(shortcut) : undefined,
+        "aria-haspopup": open.dialog ? "dialog" : undefined,
+      },
+      messages.openFileLink,
+    );
+    link.addEventListener("click", () => open.onSelect());
+    if (hasDropHint) {
+      paragraph.append(" ", createElement(ownerDocument, "span", { "aria-hidden": "true" }, "·"), " ");
+    }
+    // The link and its chip wrap as one: a chip alone on a line names no action.
+    const openItem = createElement(ownerDocument, "span", { class: "cd-shell-empty-state-open-item" }, link);
+    if (shortcut) {
+      openItem.append(
+        " ",
+        createElement(
+          ownerDocument,
+          "kbd",
+          { class: "cd-shell-empty-state-key", "aria-hidden": "true" },
+          shortcut,
+        ),
+      );
+    }
+    paragraph.append(openItem);
+    return paragraph;
+  }
+  element.hidden = true;
+
+  return {
+    element,
+    isShown: () => !element.hidden,
+    setShown(shown) {
+      element.hidden = !shown;
+    },
+    focus() {
+      newDiagram.focus({ preventScroll: true });
+    },
+    destroy() {
+      element.remove();
+    },
+  };
+}

package/src/dom/web/legal.ts

@@ -0,0 +1,75 @@
+import type { ShellMessages } from "../../core/index.js";
+import { createElement } from "../element.js";
+import type { LegalLineOptions } from "../types.js";
+
+/** The Miragon legal pages (corporate-identity, skill docs-site, `miragon/legal.ts`). */
+export const MIRAGON_HOME = "https://www.miragon.io/";
+export const MIRAGON_IMPRESSUM = "https://www.miragon.io/impressum/";
+export const MIRAGON_DATENSCHUTZ = "https://www.miragon.io/datenschutz/";
+
+export interface LegalLineContext {
+  ownerDocument: Document;
+  messages: ShellMessages;
+  options: LegalLineOptions;
+  /** `cd-shell-legal-N`: the prefix of the id the links' `aria-describedby` names. */
+  idPrefix: string;
+}
+
+export interface LegalLineController {
+  /** The `<nav data-chrome="legal">`. */
+  readonly element: HTMLElement;
+  destroy(): void;
+}
+
+/**
+ * `<nav class="cd-shell-legal" data-chrome="legal" aria-label="Legal">` (guide §5.10, §2): one
+ * line, 13px, line height 20px, at `left: 12px; bottom: 12px`, glass without border and shadow,
+ * padding `0 8px`, radius `sm`, layer 20; in a container too narrow for it, it wraps between its
+ * entries and grows upwards. Links in `--cd-ui-link`, `target="_blank" rel="noopener noreferrer"`
+ * and `aria-describedby` a hidden `messages.opensInNewTab`, each after the first in a
+ * `<span class="cd-shell-legal-item">` with its separator `<span aria-hidden="true">·</span>`:
+ * `messages.copyright(year)` → `MIRAGON_HOME`, "Impressum" → `MIRAGON_IMPRESSUM` and "Datenschutz"
+ * → `MIRAGON_DATENSCHUTZ` (both `lang="de"`, never translated), then `options.links`.
+ */
+export function createLegalLine(context: LegalLineContext): LegalLineController {
+  const { ownerDocument, messages, options } = context;
+  const year = options.year ?? new Date().getFullYear();
+
+  // Every link opens a new tab; screen readers hear that from one shared description.
+  const newTabId = `${context.idPrefix}-new-tab`;
+  const link = (label: string, href: string, lang?: string): HTMLAnchorElement =>
+    createElement(
+      ownerDocument,
+      "a",
+      { href, lang, target: "_blank", rel: "noopener noreferrer", "aria-describedby": newTabId },
+      label,
+    );
+  const separator = (): HTMLElement => createElement(ownerDocument, "span", { "aria-hidden": "true" }, "·");
+  const item = (anchor: HTMLAnchorElement): HTMLElement =>
+    createElement(ownerDocument, "span", { class: "cd-shell-legal-item" }, separator(), anchor);
+
+  // The legal pages are German whatever the tool's language (guide §2), so their names are too.
+  const links = [
+    link(messages.copyright(year), MIRAGON_HOME),
+    link("Impressum", MIRAGON_IMPRESSUM, "de"),
+    link("Datenschutz", MIRAGON_DATENSCHUTZ, "de"),
+    ...(options.links ?? []).map((extra) => link(extra.label, extra.href, extra.lang)),
+  ];
+
+  const element = createElement(ownerDocument, "nav", {
+    class: "cd-shell-legal",
+    "data-chrome": "legal",
+    "aria-label": messages.legal,
+  });
+  element.append(
+    ...links.map((anchor, index) => (index === 0 ? anchor : item(anchor))),
+    createElement(ownerDocument, "span", { id: newTabId, hidden: "" }, messages.opensInNewTab),
+  );
+
+  return {
+    element,
+    destroy() {
+      element.remove();
+    },
+  };
+}