Merge branch 'main' into 50-color-class-attributes

Author: FelixTJDietrich

.changeset/thick-geese-invent.md

@@ -0,0 +1,5 @@
+---
+"@tumaet/apollon": minor
+---
+
+Select and move several elements at once: a new multi-select toggle in the canvas controls lets you build a selection by clicking or tapping elements to add or remove them — and, with a mouse, by dragging a selection box across the canvas. It needs no keyboard, so groups can be positioned together on phones and tablets too. Click empty canvas or press Escape to clear.

library/lib/App.tsx

@@ -44,6 +44,7 @@ import {
 import { diagramNodeTypes } from "./nodes"
 import { useDiagramModifiable } from "./hooks/useDiagramModifiable"
 import { useKeyboardShortcuts } from "./hooks/useKeyboardShortcuts"
+import { useMultiSelectionMode } from "./hooks/useMultiSelectionMode"
 import { usePaneClicked } from "./hooks/usePaneClicked"
 import {
   useRemoteDraggingNodes,
@@ -144,6 +145,7 @@ function App({ onReactFlowInit, collaboration, awareness }: AppProps) {
   const { onBeforeDelete, onNodeDoubleClick, onEdgeDoubleClick } =
     useElementInteractions()
   const { onPaneClicked } = usePaneClicked()
+  const multiSelectionMode = useMultiSelectionMode()
 
   const handleReactFlowInit = useCallback(
     (instance: ReactFlowInstance) => {
@@ -245,13 +247,22 @@ function App({ onReactFlowInit, collaboration, awareness }: AppProps) {
             nodesDraggable={isDiagramModifiable}
             panOnScroll={!scrollLock || scrollEnabled}
             zoomOnScroll={!scrollLock || scrollEnabled}
-            // Keep the default left-drag pan (panOnDrag=true) — we do NOT switch
-            // to selectionOnDrag/space-pan. Adding Shift to multiSelectionKeyCode
-            // makes Shift+CLICK on a node/edge toggle it in/out of the
-            // multi-selection. selectionKeyCode keeps its default (Shift), so a
-            // Shift+DRAG on the empty pane still box-selects — no conflict, since
-            // a click on a node and a drag on the pane are different surfaces.
+            // Shift is also selectionKeyCode's default, but there's no conflict:
+            // a click on a node and a Shift+drag on the pane are different
+            // surfaces.
             multiSelectionKeyCode={["Shift", "Meta", "Control"]}
+            // With multiSelectionActive forced on, React Flow's pointerdown
+            // select would toggle the pressed node OUT of the selection and drop
+            // it from the group drag; selecting on click keeps the group whole.
+            selectNodesOnDrag={!multiSelectionMode}
+            // In the mode, a plain left-drag on the pane draws a selection box;
+            // panning moves to middle/right-drag (scroll/trackpad already pans
+            // by default). This is mouse-only by construction: d3-zoom gates the
+            // pan buttons on `mousedown` alone, so a touch drag ignores the [1,2]
+            // gate and keeps panning through the separate touch handler — which
+            // is why a one-finger drag never box-selects and pinch-zoom survives.
+            selectionOnDrag={multiSelectionMode}
+            panOnDrag={multiSelectionMode ? [1, 2] : true}
             // Delete the current selection with either key (Backspace on macOS,
             // Delete on full keyboards).
             deleteKeyCode={["Backspace", "Delete"]}

library/lib/chrome/builtins/ZoomControls.tsx

@@ -1,7 +1,18 @@
 import { useReactFlow, useStore } from "@xyflow/react"
 import { useShallow } from "zustand/shallow"
-import { Maximize, Redo2, Undo2, ZoomIn, ZoomOut } from "lucide-react"
-import { useDiagramStore, useOverlayStore } from "@/store/context"
+import {
+  Maximize,
+  Redo2,
+  SquareMousePointer,
+  Undo2,
+  ZoomIn,
+  ZoomOut,
+} from "lucide-react"
+import {
+  useDiagramStore,
+  useMetadataStore,
+  useOverlayStore,
+} from "@/store/context"
 import { insetAwareFitView } from "@/overlay/fitView"
 import { Tooltip } from "@/components/ui"
 import { useLabels } from "@/i18n/useLabels"
@@ -13,8 +24,8 @@ export interface ZoomControlsProps {
 }
 
 /**
- * The zoom / history cluster: a [zoom-out][%-reset][zoom-in][fit] island and a
- * separate [undo][redo] history island. The fit button reserves the current insets
+ * The canvas cluster: a [zoom-out][%-reset][zoom-in][fit][multi-select] island and
+ * a separate [undo][redo] history island. The fit button reserves the current insets
  * so content frames clear of the chrome. `history: false` drops the history island.
  * One `role="toolbar"` spans both islands so a single Tab stop + arrows rove every
  * button (roving-tabindex, APG-valid at ≥3 controls).
@@ -36,6 +47,13 @@ export function ZoomControls({ history = true }: ZoomControlsProps) {
     }))
   )
 
+  const { multiSelectionMode, setMultiSelectionMode } = useMetadataStore(
+    useShallow((state) => ({
+      multiSelectionMode: state.multiSelectionMode,
+      setMultiSelectionMode: state.setMultiSelectionMode,
+    }))
+  )
+
   const { ref: toolbarRef, onKeyDown: onToolbarKeyDown } =
     useRovingToolbar<HTMLDivElement>()
 
@@ -90,6 +108,17 @@ export function ZoomControls({ history = true }: ZoomControlsProps) {
             <Maximize width={18} height={18} aria-hidden="true" />
           </button>
         </Tooltip>
+        <Tooltip title={t.multiSelectionHint}>
+          <button
+            type="button"
+            className="apollon-chrome-iconbtn apollon-chrome-iconbtn--toggle"
+            onClick={() => setMultiSelectionMode(!multiSelectionMode)}
+            aria-label={t.multiSelection}
+            aria-pressed={multiSelectionMode}
+          >
+            <SquareMousePointer width={18} height={18} aria-hidden="true" />
+          </button>
+        </Tooltip>
       </div>
 
       {history && undoManagerExist && (

library/lib/hooks/useKeyboardShortcuts.ts

@@ -1,5 +1,5 @@
 import { useEffect, useRef } from "react"
-import { useDiagramStore } from "@/store/context"
+import { useDiagramStore, useMetadataStore } from "@/store/context"
 import { useShallow } from "zustand/shallow"
 import { useSelectionForCopyPaste } from "./useSelectionForCopyPaste"
 import { useDiagramModifiable } from "./useDiagramModifiable"
@@ -16,6 +16,9 @@ export const useKeyboardShortcuts = () => {
       undoManager: state.undoManager,
     }))
   )
+  const setMultiSelectionMode = useMetadataStore(
+    (state) => state.setMultiSelectionMode
+  )
   const isDiagramModifiable = useDiagramModifiable()
   const {
     selectedElementIds,
@@ -42,6 +45,7 @@ export const useKeyboardShortcuts = () => {
 
       if (event.key === "Escape") {
         event.preventDefault()
+        setMultiSelectionMode(false)
         clearSelection()
         return
       }
@@ -142,5 +146,6 @@ export const useKeyboardShortcuts = () => {
     copySelectedElements,
     cutSelectedElements, // Add this to dependencies
     pasteElements,
+    setMultiSelectionMode,
   ])
 }

library/lib/hooks/useMultiSelectionMode.ts

@@ -0,0 +1,40 @@
+import { useEffect } from "react"
+import { useStoreApi } from "@xyflow/react"
+import { useMetadataStore } from "@/store/context"
+
+/**
+ * Reproduces Shift/Ctrl multi-selection while `multiSelectionMode` is on, for
+ * pointers that have no modifier key (touch). React Flow has no public prop for
+ * "a modifier is held" — `multiSelectionKeyCode` needs a real key — so the
+ * internal flag its click paths read is the only lever. React Flow's key handler
+ * rewrites that flag on every modifier transition, hence the re-asserting
+ * subscription rather than a one-shot write.
+ *
+ * Being internal, the flag could be renamed in any React Flow release: this
+ * hook's unit test asserts it against a real store, so a rename fails CI on the
+ * catalog bump instead of silently leaving the toggle inert.
+ */
+export const useMultiSelectionMode = (): boolean => {
+  const multiSelectionMode = useMetadataStore(
+    (state) => state.multiSelectionMode
+  )
+  const store = useStoreApi()
+
+  useEffect(() => {
+    if (!multiSelectionMode) return
+
+    store.setState({ multiSelectionActive: true })
+    const unsubscribe = store.subscribe((state) => {
+      if (!state.multiSelectionActive) {
+        store.setState({ multiSelectionActive: true })
+      }
+    })
+
+    return () => {
+      unsubscribe()
+      store.setState({ multiSelectionActive: false })
+    }
+  }, [multiSelectionMode, store])
+
+  return multiSelectionMode
+}

library/lib/i18n/labels.ts

@@ -5,7 +5,7 @@
  * control of word order.
  */
 export interface ApollonLabels {
-  // Zoom / history cluster
+  // Zoom / history / multi-select cluster
   zoomToolbar: string
   zoomIn: string
   zoomOut: string
@@ -19,6 +19,8 @@ export interface ApollonLabels {
   undoHint: string
   redo: string
   redoHint: string
+  multiSelection: string
+  multiSelectionHint: string
 
   // Minimap
   miniMap: string
@@ -289,7 +291,7 @@ function defaultNodeTypeLabel(nodeType?: string): string {
 
 /** The shipped English strings — the fallback for any key a host doesn't override. */
 export const DEFAULT_LABELS: ApollonLabels = Object.freeze<ApollonLabels>({
-  zoomToolbar: "Zoom and history controls",
+  zoomToolbar: "Zoom, history and selection controls",
   zoomIn: "Zoom in",
   zoomOut: "Zoom out",
   fitView: "Fit view",
@@ -299,6 +301,8 @@ export const DEFAULT_LABELS: ApollonLabels = Object.freeze<ApollonLabels>({
   undoHint: "Undo (Ctrl+Z)",
   redo: "Redo",
   redoHint: "Redo (Ctrl+Y or Ctrl+Shift+Z)",
+  multiSelection: "Select multiple elements",
+  multiSelectionHint: "Select multiple: click elements to add or remove",
   miniMap: "Mini map",
   showMinimap: "Show minimap",
   showMinimapHint: "Show minimap (overview)",

library/lib/store/metadataStore.ts

@@ -18,6 +18,8 @@ export type MetadataStore = {
   readonly: boolean
   debug: boolean
   scrollLock: boolean
+  /** Tool toggle: clicks/taps add or remove elements — the touch path to a multi-selection. */
+  multiSelectionMode: boolean
   /** User-facing strings for the editor's own chrome; host-overridable for i18n. */
   labels: ApollonLabels
   /** Element-tag authoring config; disabled until a host opts in. */
@@ -34,6 +36,7 @@ export type MetadataStore = {
   setAvailableViews: (availableViews: ApollonView[]) => void
   setReadonly: (readonly: boolean) => void
   setScrollLock: (scrollLock: boolean) => void
+  setMultiSelectionMode: (multiSelectionMode: boolean) => void
   setLabels: (labels: ApollonLabels) => void
   setTagConfig: (tagConfig: TagConfig) => void
   setScrollEnabled: (scrollEnabled: boolean) => void
@@ -65,6 +68,7 @@ type InitialMetadataState = {
   readonly: boolean
   debug: boolean
   scrollLock: boolean
+  multiSelectionMode: boolean
   labels: ApollonLabels
   tagConfig: TagConfig
   scrollEnabled: boolean
@@ -86,6 +90,7 @@ const initialMetadataState: InitialMetadataState = {
   readonly: false,
   debug: false,
   scrollLock: false,
+  multiSelectionMode: false,
   labels: DEFAULT_LABELS,
   tagConfig: DISABLED_TAG_CONFIG,
   scrollEnabled: false,
@@ -179,6 +184,10 @@ export const createMetadataStore = (
           set({ scrollLock }, undefined, "setScrollLock")
         },
 
+        setMultiSelectionMode: (multiSelectionMode: boolean) => {
+          set({ multiSelectionMode }, undefined, "setMultiSelectionMode")
+        },
+
         setLabels: (labels) => {
           // Skip the write when the merged labels are value-equal to the current
           // set. Hosts routinely pass an inline `labels={{…}}` literal (new object

library/lib/styles/app.css

@@ -454,6 +454,36 @@
    too (App.tsx), so editor chrome still gets it; it references only chrome tokens
    so the rendered control is identical wherever the class is defined. */
 
+/* Opt-in `--toggle` peer: an unqualified `[aria-pressed="true"]` here would paint
+   every future editor chrome toggle, and the home band's pills (components.css)
+   already paint their own on-state. The hover/active peers exist because the base
+   button's own state rules would otherwise overwrite the pressed fill. */
+.apollon-chrome-iconbtn--toggle[aria-pressed="true"] {
+  background: color-mix(in srgb, var(--apollon-chrome-accent) 18%, transparent);
+  color: var(--apollon-chrome-accent);
+}
+
+.apollon-chrome-iconbtn--toggle[aria-pressed="true"]:hover:not(:disabled) {
+  background: color-mix(in srgb, var(--apollon-chrome-accent) 26%, transparent);
+}
+
+.apollon-chrome-iconbtn--toggle[aria-pressed="true"]:active:not(:disabled) {
+  background: color-mix(in srgb, var(--apollon-chrome-accent) 34%, transparent);
+}
+
+/* Forced colours drop the accent fill, which is this toggle's ONLY signal that a
+   mode is armed — repaint it with the system pair so the mode stays visible. The
+   hover/active peers are re-listed because their higher specificity would
+   otherwise restore the (now-invisible) accent fill. */
+@media (forced-colors: active) {
+  .apollon-chrome-iconbtn--toggle[aria-pressed="true"],
+  .apollon-chrome-iconbtn--toggle[aria-pressed="true"]:hover:not(:disabled),
+  .apollon-chrome-iconbtn--toggle[aria-pressed="true"]:active:not(:disabled) {
+    background: Highlight;
+    color: HighlightText;
+  }
+}
+
 /* Expanded minimap = its own glass card (the .react-flow__panel glass rule
    supplies the pane). Drop the panel padding so the map fills the rounded card
    (no fat glass gutter) and clip the svg to the card radius. */

library/tests/unit/useMultiSelectionMode.test.tsx

@@ -0,0 +1,53 @@
+import { describe, it, expect, beforeEach } from "vitest"
+import { act, renderHook } from "@testing-library/react"
+import { type ReactNode } from "react"
+import { ReactFlowProvider, useStoreApi } from "@xyflow/react"
+import * as Y from "yjs"
+import { MetadataStoreContext } from "@/store/context"
+import { createMetadataStore } from "@/store/metadataStore"
+import { useMultiSelectionMode } from "@/hooks/useMultiSelectionMode"
+
+describe("useMultiSelectionMode", () => {
+  let metadataStore: ReturnType<typeof createMetadataStore>
+
+  const wrapper = ({ children }: { children: ReactNode }) => (
+    <MetadataStoreContext value={metadataStore}>
+      <ReactFlowProvider>{children}</ReactFlowProvider>
+    </MetadataStoreContext>
+  )
+
+  /** Renders the hook and hands back the React Flow store it drives. */
+  const renderMultiSelectionMode = () =>
+    renderHook(
+      () => {
+        useMultiSelectionMode()
+        return useStoreApi()
+      },
+      { wrapper }
+    )
+
+  beforeEach(() => {
+    metadataStore = createMetadataStore(new Y.Doc())
+  })
+
+  it("forces React Flow's multiSelectionActive while the mode is on", () => {
+    const { result } = renderMultiSelectionMode()
+    expect(result.current.getState().multiSelectionActive).toBe(false)
+
+    act(() => metadataStore.getState().setMultiSelectionMode(true))
+    expect(result.current.getState().multiSelectionActive).toBe(true)
+
+    act(() => metadataStore.getState().setMultiSelectionMode(false))
+    expect(result.current.getState().multiSelectionActive).toBe(false)
+  })
+
+  it("re-asserts the flag when React Flow's key handler clears it", () => {
+    const { result } = renderMultiSelectionMode()
+    act(() => metadataStore.getState().setMultiSelectionMode(true))
+
+    // React Flow writes this flag from its own modifier-key handler on every
+    // key transition, which would silently break toggle-taps mid-mode.
+    act(() => result.current.setState({ multiSelectionActive: false }))
+    expect(result.current.getState().multiSelectionActive).toBe(true)
+  })
+})

standalone/webapp/tests/e2e/controls-a11y.spec.ts

@@ -42,7 +42,7 @@ test.describe("built-in controls accessibility", () => {
     page,
   }) => {
     const toolbar = page.getByRole("toolbar", {
-      name: "Zoom and history controls",
+      name: "Zoom, history and selection controls",
     })
     await expect(toolbar).toBeVisible()
 
@@ -54,22 +54,23 @@ test.describe("built-in controls accessibility", () => {
     await tabbable.focus()
     expect(await activeLabel(page)).toBe("Zoom out")
 
-    // ArrowRight roves across BOTH glass islands (view [−][%][+][fit] then
-    // history), staying a single tab stop — the toolbar spans both islands.
+    // ArrowRight roves across BOTH glass islands (view [−][%][+][fit][multi-
+    // select] then history), staying a single tab stop — the toolbar spans
+    // both islands.
     await page.keyboard.press("ArrowRight")
     expect(await activeLabel(page)).toBe("Zoom is 100%, reset to 100%")
     await expect(toolbar.locator("button[tabindex='0']")).toHaveCount(1)
 
     // End jumps to the last ENABLED control (roving skips disabled buttons). With
     // a freshly-loaded diagram the history island is either absent (no undo
     // manager) or its undo/redo start disabled, so the last reachable control is
-    // the fit-view button; if an enabled redo is present it is "Redo". Assert the
-    // concrete last DOM control — not merely "not the first".
+    // the multi-select toggle; if an enabled redo is present it is "Redo". Assert
+    // the concrete last DOM control — not merely "not the first".
     const expectedLast = await toolbar
       .locator("button:enabled")
       .last()
       .getAttribute("aria-label")
-    expect(["Fit view", "Redo"]).toContain(expectedLast)
+    expect(["Select multiple elements", "Redo"]).toContain(expectedLast)
     await page.keyboard.press("End")
     expect(await activeLabel(page)).toBe(expectedLast)