feat: save with Ctrl+S, duplicate with Ctrl+D, and a keyboard-driven viewport (#817)

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: FelixTJDietrich

.changeset/drag-and-drop-diagram-import.md

@@ -0,0 +1,5 @@
+---
+"@tumaet/webapp": minor
+---
+
+Drag a `.json` diagram exported from Apollon anywhere onto the app to import it — it opens as a new diagram, leaving whatever you had open untouched. A drop overlay confirms the target, and the File-menu "Import" item takes the same path.

.changeset/duplicate-and-zoom-from-the-keyboard.md

@@ -0,0 +1,7 @@
+---
+"@tumaet/apollon": minor
+---
+
+Duplicates the selection with Ctrl/Cmd+D — edges between the duplicated elements included — and puts the viewport on the keyboard: Ctrl/Cmd+= and Ctrl/Cmd+- to zoom, Ctrl/Cmd+0 for 100%, Ctrl/Cmd+Shift+1 and Ctrl/Cmd+Shift+2 to fit the diagram or the selection. Esc still clears the selection, which Ctrl/Cmd+D used to do. Zooming, copying and selecting now work on a read-only diagram, shortcuts stay out of open dialogs and half-typed IME characters, and holding a key repeats only undo, redo and zoom.
+
+For embedders: `APOLLON_SHORTCUTS` lists every key the editor consumes, alongside `matchesShortcutCombo`, `isTypingTarget`, `isInsideOverlay` and `shortcutKeyName` — enough to render a shortcut sheet that tracks the editor, or to bind your own keys under the same rules. Pass `keyboardShortcuts: false` to keep the editor off the keyboard entirely.

.changeset/save-a-diagram-with-ctrl-s.md

@@ -0,0 +1,5 @@
+---
+"@tumaet/webapp": minor
+---
+
+Saves the diagram as a JSON file with Ctrl/Cmd+S, instead of the browser offering to save the page. Ctrl/Cmd+Shift+S now writes a version to history straight away — it used to only open the panel. The "How to use this editor?" dialog lists every shortcut with the keys your own keyboard prints — ⌘⇧Z on a Mac, Ctrl+Shift+Z everywhere else — and its viewport tips now match what the canvas does: scroll or drag pans, Ctrl/Cmd+scroll zooms.

docs/library/api.md

@@ -72,16 +72,17 @@ afterwards. Re-key the component to apply them to a new editor.
 changes; no rebuild. Passing `undefined` for any reactive prop leaves the
 live value untouched (no reset). Re-key the component to fully reset.
 
-| Prop          | Type                     | Maps to                                     |
-| ------------- | ------------------------ | ------------------------------------------- |
-| `readonly`    | `boolean`                | `editor.setReadonly(value)`                 |
-| `view`        | `ApollonView`            | `editor.view = value`                       |
-| `mode`        | `ApollonMode`            | `editor.setMode(value)`                     |
-| `scrollLock`  | `boolean`                | `editor.setScrollLock(value)`               |
-| `labels`      | `Partial<ApollonLabels>` | `editor.setLabels(value)`                   |
-| `tags`        | `boolean \| TagOptions`  | `editor.setTags(value)`                     |
-| `previewMode` | `boolean`                | `editor.setPreviewMode(value)`              |
-| `model`       | `UMLModel`               | `editor.model = value` — controlled overlay |
+| Prop                | Type                     | Maps to                                     |
+| ------------------- | ------------------------ | ------------------------------------------- |
+| `readonly`          | `boolean`                | `editor.setReadonly(value)`                 |
+| `view`              | `ApollonView`            | `editor.view = value`                       |
+| `mode`              | `ApollonMode`            | `editor.setMode(value)`                     |
+| `scrollLock`        | `boolean`                | `editor.setScrollLock(value)`               |
+| `keyboardShortcuts` | `boolean`                | `editor.setKeyboardShortcuts(value)`        |
+| `labels`            | `Partial<ApollonLabels>` | `editor.setLabels(value)`                   |
+| `tags`              | `boolean \| TagOptions`  | `editor.setTags(value)`                     |
+| `previewMode`       | `boolean`                | `editor.setPreviewMode(value)`              |
+| `model`             | `UMLModel`               | `editor.model = value` — controlled overlay |
 
 **Lifecycle.**
 
@@ -262,6 +263,68 @@ These members are only meaningful with `collaborationEnabled: true`. See
 the [Conversion API](/library/api/conversion-api) to convert models to
 SVG/PNG/PDF over HTTP via the standalone server.
 
+## Keyboard shortcuts
+
+`Mod` is Ctrl on Windows/Linux and Cmd on macOS; combos marked _view_ work on
+read-only diagrams too. Nothing fires while the user is typing in a field or
+while a dialog or menu is open.
+
+| Combo                          | Action                                   |
+| ------------------------------ | ---------------------------------------- |
+| `Mod+A` / `Esc`                | Select all / clear selection (_view_)    |
+| `Delete` / `Backspace`         | Delete selection                         |
+| `Mod+C` / `Mod+X` / `Mod+V`    | Copy (_view_) / cut / paste              |
+| `Mod+D`                        | Duplicate the selection beside itself    |
+| Arrow keys                     | Nudge selection                          |
+| `Mod+Z`, `Mod+Shift+Z`/`Mod+Y` | Undo, redo                               |
+| `Mod+=` / `Mod+-`              | Zoom in / out (_view_)                   |
+| `Mod+0`                        | Reset zoom to 100% (_view_)              |
+| `Mod+Shift+1` / `Mod+Shift+2`  | Zoom to fit / zoom to selection (_view_) |
+
+Figma and Excalidraw put the last two on `Shift+1`/`Shift+2`, but a shortcut
+whose keys produce a printable character fails
+[WCAG 2.1.4](https://www.w3.org/WAI/WCAG21/Understanding/character-key-shortcuts)
+unless it can be turned off, remapped, or scoped to focus.
+
+Pass `keyboardShortcuts: false` to keep the editor's hands off every key above —
+for a host that binds them itself, or that mounts more than one editor (they
+listen on `document`, so two would both answer).
+
+`APOLLON_SHORTCUTS` is the list the editor runs, so a host can render a sheet
+that tracks it, or check it before binding a key of its own. Each entry's
+**first** combo is the primary one — a sheet should render only that; the rest
+are aliases (`Mod+Y` redo, layout variants of `Mod+=`). Entries flagged
+`canvasHandled` are React Flow's, not the editor's own handler. `shortcutKeyName`
+turns a combo into the key it names, so a sheet renders "1" rather than the
+`Digit1` code that combo matches on.
+
+`matchesShortcutCombo`, `isTypingTarget` and `isInsideOverlay` are the
+primitives that handler matches and stands down with, exported so a host's own
+keys behave like the editor's:
+
+```ts
+import {
+  isInsideOverlay,
+  isTypingTarget,
+  matchesShortcutCombo,
+  type ApollonShortcutCombo,
+} from "@tumaet/apollon"
+
+const rename: ApollonShortcutCombo = { key: "r", mod: true }
+
+document.addEventListener("keydown", (event) => {
+  if (event.isComposing || isTypingTarget(event) || isInsideOverlay(event)) {
+    return
+  }
+  if (!matchesShortcutCombo(event, rename)) return
+  event.preventDefault()
+})
+```
+
+A combo matching on `key` follows what the user's layout prints and is compared
+case-insensitively; use `code` for digits, whose character moves between layouts
+and under Shift.
+
 ## Diagram types
 
 Enum literals (the strings on the wire and in `UMLModel.type`) on the left;

library/lib/App.tsx

@@ -100,6 +100,7 @@ function App({ onReactFlowInit, collaboration, awareness }: AppProps) {
     readonly,
     scrollLock,
     scrollEnabled,
+    keyboardShortcuts,
     connectionGuidanceActive,
     startReconnectPreview,
     stopReconnectPreview,
@@ -109,6 +110,7 @@ function App({ onReactFlowInit, collaboration, awareness }: AppProps) {
       readonly: state.readonly,
       scrollLock: state.scrollLock,
       scrollEnabled: state.scrollEnabled,
+      keyboardShortcuts: state.keyboardShortcuts,
       connectionGuidanceActive: state.connectionGuidanceActive,
       startReconnectPreview: state.startReconnectPreview,
       stopReconnectPreview: state.stopReconnectPreview,
@@ -264,8 +266,14 @@ function App({ onReactFlowInit, collaboration, awareness }: AppProps) {
             selectionOnDrag={multiSelectionMode}
             panOnDrag={multiSelectionMode ? [1, 2] : true}
             // Delete the current selection with either key (Backspace on macOS,
-            // Delete on full keyboards).
-            deleteKeyCode={["Backspace", "Delete"]}
+            // Delete on full keyboards) — but hand these keys back with the
+            // editor's other shortcuts when a host opts out via
+            // `keyboardShortcuts: false`. `onBeforeDelete` additionally blocks a
+            // delete whose focus is inside an overlay over the canvas.
+            deleteKeyCode={keyboardShortcuts ? ["Backspace", "Delete"] : []}
+            // Arrow-key node nudging + Enter/Escape selection a11y are React
+            // Flow's; disable them together with the rest when shortcuts are off.
+            disableKeyboardA11y={!keyboardShortcuts}
           >
             <CustomBackground />
             <AlignmentGuides />

library/lib/apollon-editor.tsx

@@ -234,6 +234,11 @@ export class ApollonEditor {
     if (options?.scrollLock !== undefined) {
       this.metadataStore.getState().setScrollLock(options.scrollLock)
     }
+    if (options?.keyboardShortcuts !== undefined) {
+      this.metadataStore
+        .getState()
+        .setKeyboardShortcuts(options.keyboardShortcuts)
+    }
     if (options?.labels !== undefined) {
       this.metadataStore.getState().setLabels(mergeLabels(options.labels))
     }
@@ -934,6 +939,14 @@ export class ApollonEditor {
     this.metadataStore.getState().setScrollLock(scrollLock)
   }
 
+  /**
+   * Live-toggle whether the editor answers its keyboard shortcuts (see
+   * `APOLLON_SHORTCUTS`), React Flow's delete and arrow-key moving included.
+   */
+  public setKeyboardShortcuts(keyboardShortcuts: boolean): void {
+    this.metadataStore.getState().setKeyboardShortcuts(keyboardShortcuts)
+  }
+
   /**
    * Replace the editor's user-facing strings (i18n). Merged over the English
    * defaults, so a partial map only changes the keys it provides. Reactive — the

library/lib/chrome/builtins/ZoomControls.tsx

@@ -14,6 +14,7 @@ import {
   useOverlayStore,
 } from "@/store/context"
 import { insetAwareFitView } from "@/overlay/fitView"
+import { ariaKeyshortcuts } from "@/keyboard"
 import { Tooltip } from "@/components/ui"
 import { useLabels } from "@/i18n/useLabels"
 import { useRovingToolbar } from "../useRovingToolbar"
@@ -72,6 +73,7 @@ export function ZoomControls({ history = true }: ZoomControlsProps) {
             type="button"
             className="apollon-chrome-iconbtn"
             onClick={() => rf.zoomOut()}
+            aria-keyshortcuts={ariaKeyshortcuts("zoom-out")}
             aria-label={t.zoomOut}
           >
             <ZoomOut width={18} height={18} aria-hidden="true" />
@@ -83,6 +85,7 @@ export function ZoomControls({ history = true }: ZoomControlsProps) {
             type="button"
             className="apollon-chrome-iconbtn apollon-chrome-iconbtn--readout"
             onClick={() => rf.zoomTo(1)}
+            aria-keyshortcuts={ariaKeyshortcuts("reset-zoom")}
             aria-label={t.zoomReadout(zoomLevelPercent)}
           >
             {zoomLevelPercent}%
@@ -93,6 +96,7 @@ export function ZoomControls({ history = true }: ZoomControlsProps) {
             type="button"
             className="apollon-chrome-iconbtn"
             onClick={() => rf.zoomIn()}
+            aria-keyshortcuts={ariaKeyshortcuts("zoom-in")}
             aria-label={t.zoomIn}
           >
             <ZoomIn width={18} height={18} aria-hidden="true" />
@@ -103,6 +107,7 @@ export function ZoomControls({ history = true }: ZoomControlsProps) {
             type="button"
             className="apollon-chrome-iconbtn"
             onClick={() => insetAwareFitView(rf, insets, safeArea)}
+            aria-keyshortcuts={ariaKeyshortcuts("fit-view")}
             aria-label={t.fitView}
           >
             <Maximize width={18} height={18} aria-hidden="true" />
@@ -129,6 +134,7 @@ export function ZoomControls({ history = true }: ZoomControlsProps) {
                 type="button"
                 className="apollon-chrome-iconbtn"
                 onClick={undo}
+                aria-keyshortcuts={ariaKeyshortcuts("undo")}
                 disabled={!canUndo}
                 aria-label={t.undo}
               >
@@ -142,6 +148,7 @@ export function ZoomControls({ history = true }: ZoomControlsProps) {
                 type="button"
                 className="apollon-chrome-iconbtn"
                 onClick={redo}
+                aria-keyshortcuts={ariaKeyshortcuts("redo")}
                 disabled={!canRedo}
                 aria-label={t.redo}
               >

library/lib/components/react/Apollon.tsx

@@ -68,6 +68,12 @@ export interface ApollonProps {
   view?: ApollonView
   mode?: ApollonMode
   scrollLock?: boolean
+  /**
+   * Answer the editor's keyboard shortcuts (see `APOLLON_SHORTCUTS`), including
+   * React Flow's delete and arrow-key moving. Set `false` where the host binds
+   * those keys itself, or mounts more than one editor. Default `true`.
+   */
+  keyboardShortcuts?: boolean
   /** Override the editor's own strings for i18n. See {@link ApollonEditor.setLabels}. */
   labels?: Partial<ApollonLabels>
   /** Enable + configure element-tag authoring. See {@link ApollonEditor.setTags}. */
@@ -118,6 +124,7 @@ export function Apollon(props: ApollonProps) {
     view,
     mode,
     scrollLock,
+    keyboardShortcuts,
     labels,
     tags,
     previewMode,
@@ -200,6 +207,12 @@ export function Apollon(props: ApollonProps) {
     if (editor && scrollLock !== undefined) editor.setScrollLock(scrollLock)
   }, [editor, scrollLock])
 
+  useEffect(() => {
+    if (editor && keyboardShortcuts !== undefined) {
+      editor.setKeyboardShortcuts(keyboardShortcuts)
+    }
+  }, [editor, keyboardShortcuts])
+
   useEffect(() => {
     if (editor && labels !== undefined) editor.setLabels(labels)
   }, [editor, labels])

library/lib/hooks/useElementInteractions.ts

@@ -10,6 +10,7 @@ import {
 } from "@xyflow/react"
 import { useShallow } from "zustand/shallow"
 import { useDiagramModifiable } from "./useDiagramModifiable"
+import { isElementInOverlay } from "@/keyboard"
 
 export const useElementInteractions = () => {
   const isDiagramModifiable = useDiagramModifiable()
@@ -28,7 +29,14 @@ export const useElementInteractions = () => {
   const canOpenPopover = isDiagramModifiable || canOpenAssessmentPopover
 
   const onBeforeDelete: OnBeforeDelete = () => {
-    return new Promise((resolve) => resolve(isDiagramModifiable))
+    // React Flow's Delete listener is document-level, so a Delete pressed while
+    // focus is in a dialog or menu over the canvas would otherwise remove the
+    // selection behind it. Block that here — the one place every RF deletion
+    // funnels through — the same way the editor's own shortcuts stand down.
+    if (isElementInOverlay(document.activeElement)) {
+      return Promise.resolve(false)
+    }
+    return Promise.resolve(isDiagramModifiable)
   }
 
   const onNodeDoubleClick: NodeMouseHandler<Node> = (_event, node) => {