feat(core,nodes): implement a11y in nodes

Signed-off-by: braks <78412429+bcakmakoglu@users.noreply.github.com>

packages/core/src/auto-imports.d.ts

@@ -22,11 +22,12 @@ declare global {
   const addEdgeToStore: typeof import('./utils/store')['addEdgeToStore']
   const applyChanges: typeof import('./utils/changes')['applyChanges']
   const applyEdgeChanges: typeof import('./utils/changes')['applyEdgeChanges']
-  const applyExtent: typeof import('./utils/drag')['applyExtent']
   const applyNodeChanges: typeof import('./utils/changes')['applyNodeChanges']
+  const arrowKeyDiffs: typeof import('./utils/a11y')['arrowKeyDiffs']
   const asyncComputed: typeof import('@vueuse/core')['asyncComputed']
   const autoResetRef: typeof import('@vueuse/core')['autoResetRef']
   const boxToRect: typeof import('./utils/graph')['boxToRect']
+  const calcNextPosition: typeof import('./utils/drag')['calcNextPosition']
   const checkElementBelowIsValid: typeof import('./composables/useHandle')['checkElementBelowIsValid']
   const clamp: typeof import('./utils/graph')['clamp']
   const clampPosition: typeof import('./utils/graph')['clampPosition']
@@ -72,6 +73,7 @@ declare global {
   const getEdgeId: typeof import('./utils/graph')['getEdgeId']
   const getEdgePositions: typeof import('./utils/edge')['getEdgePositions']
   const getEventHandlerParams: typeof import('./utils/drag')['getEventHandlerParams']
+  const getExtent: typeof import('./utils/drag')['getExtent']
   const getHandle: typeof import('./utils/edge')['getHandle']
   const getHandleBounds: typeof import('./utils/node')['getHandleBounds']
   const getHandlePosition: typeof import('./utils/edge')['getHandlePosition']
@@ -102,6 +104,7 @@ declare global {
   const isEdgeVisible: typeof import('./utils/edge')['isEdgeVisible']
   const isGraphEdge: typeof import('./utils/graph')['isGraphEdge']
   const isGraphNode: typeof import('./utils/graph')['isGraphNode']
+  const isInputDOMNode: typeof import('./composables/useKeyPress')['isInputDOMNode']
   const isNode: typeof import('./utils/graph')['isNode']
   const isParentSelected: typeof import('./utils/graph')['isParentSelected']
   const isProxy: typeof import('vue')['isProxy']
@@ -322,6 +325,7 @@ declare global {
   const useToString: typeof import('@vueuse/core')['useToString']
   const useToggle: typeof import('@vueuse/core')['useToggle']
   const useTransition: typeof import('@vueuse/core')['useTransition']
+  const useUpdateNodePositions: typeof import('./composables/useUpdateNodePositions')['default']
   const useUrlSearchParams: typeof import('@vueuse/core')['useUrlSearchParams']
   const useUserMedia: typeof import('@vueuse/core')['useUserMedia']
   const useVModel: typeof import('@vueuse/core')['useVModel']

packages/core/src/components/Nodes/NodeWrapper.vue

@@ -1,12 +1,14 @@
 <script lang="ts" setup>
 import { isNumber } from '@vueuse/core'
 import type { GraphNode, HandleConnectable, NodeComponent, SnapGrid, XYZPosition } from '../../types'
+import { ARIA_NODE_DESC_KEY } from '../../utils/a11y'
 
 const { id, type, name, draggable, selectable, connectable, ...props } = defineProps<{
   id: string
   draggable: boolean
   selectable: boolean
   connectable: HandleConnectable
+  focusable: boolean
   snapGrid?: SnapGrid
   type: NodeComponent | Function | Object | false
   name: string
@@ -17,6 +19,7 @@ const { id, type, name, draggable, selectable, connectable, ...props } = defineP
 provide(NodeId, id)
 
 const {
+  id: vueFlowId,
   edges,
   noPanClassName,
   selectNodesOnDrag,
@@ -33,8 +36,12 @@ const {
   nodeExtent,
   onNodesInitialized,
   elevateNodesOnSelect,
+  disableKeyboardA11y,
+  ariaLiveMessage,
 } = $(useVueFlow())
 
+const updateNodePositions = useUpdateNodePositions()
+
 const node = $(useVModel(props, 'node'))
 
 const parentNode = $computed(() => (node.parentNode ? getNode(node.parentNode) : undefined))
@@ -138,33 +145,22 @@ onNodesInitialized(() => {
   initialized.value = true
 })
 
-/** Initial clamp of node position */
 until(initialized)
   .toBe(true)
   .then(() => {
-    const extent = applyExtent(node, nodeExtent, parentNode)
+    const { computedPosition, position } = calcNextPosition(node, node.position, nodeExtent, parentNode)
 
-    const clampedPos = clampPosition(node.computedPosition, extent)
-
-    node.computedPosition = { ...node.computedPosition, ...clampedPos }
-    node.position = {
-      x: node.computedPosition.x - (parentNode?.computedPosition.x || 0),
-      y: node.computedPosition.y - (parentNode?.computedPosition.y || 0),
-    }
+    node.computedPosition = { ...node.computedPosition, ...computedPosition }
+    node.position = position
   })
 
 function updateInternals() {
   if (nodeElement.value) updateNodeDimensions([{ id, nodeElement: nodeElement.value, forceUpdate: true }])
 
-  updatePosition(
-    {
-      x: node.position.x,
-      y: node.position.y,
-      // should be using computedPosition.z but in case  it's not present, fall back to selected state
-      z: node.computedPosition.z ? node.computedPosition.z : node.selected ? 1000 : 0,
-    },
-    parentNode ? { ...parentNode.computedPosition } : undefined,
-  )
+  const { computedPosition, position } = calcNextPosition(node, node.position, nodeExtent, parentNode)
+
+  node.computedPosition = { ...node.computedPosition, ...computedPosition }
+  node.position = position
 }
 
 function onMouseEnter(event: MouseEvent) {
@@ -200,6 +196,36 @@ function onSelectNode(event: MouseEvent) {
 
   emit.click({ event, node, connectedEdges })
 }
+
+const onKeyDown = (event: KeyboardEvent) => {
+  if (isInputDOMNode(event)) return
+
+  event.preventDefault()
+
+  if (elementSelectionKeys.includes(event.key) && selectable) {
+    const unselect = event.key === 'Escape'
+
+    if (unselect) {
+      nodeElement.value?.blur()
+    }
+
+    handleNodeClick(node, multiSelectionActive, addSelectedNodes, removeSelectedElements, $$(nodesSelectionActive), unselect)
+  } else if (!disableKeyboardA11y && draggable && node.selected && arrowKeyDiffs[event.key]) {
+    $$(ariaLiveMessage).value = `Moved selected node ${event.key.replace('Arrow', '').toLowerCase()}. New position, x: ${~~node
+      .position.x}, y: ${~~node.position.y}`
+
+    // by default a node moves 5px on each key press, or 20px if shift is pressed
+    // if snap grid is enabled, we use that for the velocity.
+    const xVelo = props.snapGrid ? props.snapGrid[0] : 5
+    const yVelo = props.snapGrid ? props.snapGrid[1] : 5
+    const factor = event.shiftKey ? 4 : 1
+
+    updateNodePositions({
+      x: arrowKeyDiffs[event.key].x * xVelo * factor,
+      y: arrowKeyDiffs[event.key].y * yVelo * factor,
+    })
+  }
+}
 </script>
 
 <script lang="ts">
@@ -229,6 +255,10 @@ export default {
       pointerEvents: selectable || draggable ? 'all' : 'none',
       ...getStyle,
     }"
+    :tabIndex="focusable ? 0 : undefined"
+    :role="focusable ? 'button' : undefined"
+    :aria-describedby="disableKeyboardA11y ? undefined : `${ARIA_NODE_DESC_KEY}-${vueFlowId}`"
+    :aria-label="node.ariaLabel"
     :data-id="node.id"
     @mouseenter="onMouseEnter"
     @mousemove="onMouseMove"
@@ -236,6 +266,7 @@ export default {
     @contextmenu="onContextMenu"
     @click="onSelectNode"
     @dblclick="onDoubleClick"
+    @keydown="onKeyDown"
   >
     <component
       :is="type === false ? getNodeTypes.default : type"

packages/core/src/composables/useDrag.ts

@@ -3,7 +3,7 @@ import { drag } from 'd3-drag'
 import { select } from 'd3-selection'
 import type { Ref } from 'vue'
 import type { MaybeRef } from '@vueuse/core'
-import type { CoordinateExtent, NodeDragEvent, NodeDragItem, SnapGrid, XYPosition } from '~/types'
+import type { NodeDragEvent, NodeDragItem, SnapGrid, XYPosition } from '~/types'
 
 export type UseDragEvent = D3DragEvent<HTMLDivElement, null, SubjectPosition>
 
@@ -98,12 +98,18 @@ function useDrag(params: UseDragParams) {
                     nextPosition.y = snapY * Math.round(nextPosition.y / snapY)
                   }
 
-                  const currentExtent = applyExtent(n, nodeExtent, n.parentNode ? getNode(n.parentNode) : undefined)
+                  const { computedPosition, position } = calcNextPosition(
+                    n,
+                    nextPosition,
+                    nodeExtent,
+                    n.parentNode ? getNode(n.parentNode) : undefined,
+                  )
 
                   // we want to make sure that we only fire a change event when there is a changes
                   hasChange = hasChange || n.position.x !== nextPosition.x || n.position.y !== nextPosition.y
 
-                  n.position = currentExtent ? clampPosition(nextPosition, currentExtent as CoordinateExtent) : nextPosition
+                  n.computedPosition = { ...n.computedPosition, ...computedPosition }
+                  n.position = position
 
                   return n
                 })

packages/core/src/composables/useKeyPress.ts

@@ -2,12 +2,11 @@ import type { Ref } from 'vue'
 import type { KeyFilter, MaybeRef } from '@vueuse/core'
 import { isBoolean, isFunction } from '@vueuse/core'
 
-function isInputDOMNode(event: KeyboardEvent): boolean {
+export function isInputDOMNode(event: KeyboardEvent): boolean {
   const target = (event.composedPath?.()?.[0] || event.target) as HTMLElement
 
   // we want to be able to do a multi selection event if we are in an input field
   if (event.ctrlKey || event.metaKey || event.shiftKey) return false
-
   const hasAttribute = isFunction(target.hasAttribute) ? target.hasAttribute('contenteditable') : false
 
   const closest = isFunction(target.closest) ? target.closest('.nokey') : null

packages/core/src/composables/useUpdateNodePositions.ts

@@ -0,0 +1,32 @@
+import type { NodeDragItem, XYPosition } from '~/types'
+
+function useUpdateNodePositions() {
+  const { getSelectedNodes, nodeExtent, updateNodePositions, findNode } = useVueFlow()
+
+  return (positionDiff: XYPosition) => {
+    const nodeUpdates = getSelectedNodes.value.flatMap((n) => {
+      if (n.computedPosition) {
+        const nextPosition = { x: n.computedPosition.x + positionDiff.x, y: n.computedPosition.y + positionDiff.y }
+
+        const updatedPos = calcNextPosition(n, nextPosition, nodeExtent.value, n.parentNode ? findNode(n.parentNode) : undefined)
+
+        return [
+          {
+            id: n.id,
+            position: updatedPos.position,
+            computedPosition: { ...n.computedPosition, ...updatedPos.computedPosition },
+            from: n.position,
+            distance: { x: positionDiff.x, y: positionDiff.y },
+            dimensions: n.dimensions,
+          },
+        ] as NodeDragItem[]
+      }
+
+      return []
+    })
+
+    updateNodePositions(nodeUpdates, true, true)
+  }
+}
+
+export default useUpdateNodePositions

packages/core/src/container/EdgeRenderer/EdgeRenderer.vue

@@ -30,9 +30,7 @@ const {
 } = $(useVueFlow())
 
 const selectable = (s?: boolean) => (typeof s === 'undefined' ? elementsSelectable : s)
-
 const updatable = (u?: EdgeUpdatable) => (typeof u === 'undefined' ? edgesUpdatable : u)
-
 const focusable = (f?: boolean) => (typeof f === 'undefined' ? edgesFocusable : f)
 
 const sourceNode = $(

packages/core/src/container/NodeRenderer/NodeRenderer.vue

@@ -4,13 +4,21 @@ import type { GraphNode, HandleConnectable, NodeComponent } from '../../types'
 
 const slots = inject(Slots)
 
-const { nodesDraggable, elementsSelectable, nodesConnectable, getNodes, getNodeTypes, updateNodeDimensions, emits } = $(
-  useVueFlow(),
-)
+const {
+  nodesDraggable,
+  nodesFocusable,
+  elementsSelectable,
+  nodesConnectable,
+  getNodes,
+  getNodeTypes,
+  updateNodeDimensions,
+  emits,
+} = $(useVueFlow())
 
 const draggable = (d?: boolean) => (typeof d === 'undefined' ? nodesDraggable : d)
 const selectable = (s?: boolean) => (typeof s === 'undefined' ? elementsSelectable : s)
 const connectable = (c?: HandleConnectable) => (typeof c === 'undefined' ? nodesConnectable : c)
+const focusable = (f?: boolean) => (typeof f === 'undefined' ? nodesFocusable : f)
 
 const resizeObserver = ref<ResizeObserver>()
 
@@ -91,6 +99,7 @@ export default {
         :draggable="draggable(node.draggable)"
         :selectable="selectable(node.selectable)"
         :connectable="connectable(node.connectable)"
+        :focusable="focusable(node.focusable)"
         :node="node"
       />
     </template>

packages/core/src/container/VueFlow/VueFlow.vue

@@ -39,6 +39,8 @@ const props = withDefaults(defineProps<FlowProps>(), {
   elevateEdgesOnSelect: undefined,
   elevateNodesOnSelect: undefined,
   disableKeyboardA11y: undefined,
+  edgesFocusable: undefined,
+  nodesFocusable: undefined,
 })
 
 const emit = defineEmits<{

packages/core/src/store/state.ts

@@ -89,6 +89,7 @@ const defaultState = (): State => ({
 
   edgesUpdatable: false,
   edgesFocusable: true,
+  nodesFocusable: true,
   nodesConnectable: true,
   nodesDraggable: true,
   elementsSelectable: true,
@@ -113,6 +114,7 @@ const defaultState = (): State => ({
   elevateNodesOnSelect: true,
 
   disableKeyboardA11y: false,
+  ariaLiveMessage: '',
 
   __experimentalFeatures: {
     nestedFlow: false,

packages/core/src/types/changes.ts

@@ -1,11 +1,13 @@
-import type { Dimensions, ElementData, XYPosition } from './flow'
+import type { Dimensions, ElementData, XYPosition, XYZPosition } from './flow'
 import type { GraphNode, Node, NodeHandleBounds } from './node'
 import type { GraphEdge } from './edge'
 
 export interface NodeDragItem {
   id: string
-  // relative node position
+  // relative node position (to parent)
   position: XYPosition
+  // absolute node position
+  computedPosition: XYZPosition
   // distance from the mouse cursor to the node when start dragging
   distance: XYPosition
   dimensions: Dimensions

packages/core/src/types/flow.ts

@@ -160,6 +160,8 @@ export interface FlowProps {
   elevateNodesOnSelect?: boolean
 
   disableKeyboardA11y?: boolean
+  edgesFocusable?: boolean
+  nodesFocusable?: boolean
 
   __experimentalFeatures?: {
     nestedFlow?: boolean

packages/core/src/types/node.ts

@@ -32,6 +32,7 @@ export interface Node<Data = ElementData, CustomEvents extends Record<string, Cu
   draggable?: boolean
   selectable?: boolean
   connectable?: HandleConnectable
+  focusable?: boolean
   dragHandle?: string
   /** move on grid */
   snapGrid?: SnapGrid
@@ -72,6 +73,8 @@ export interface Node<Data = ElementData, CustomEvents extends Record<string, Cu
   data?: Data
   /** contextual and custom events that are passed to your custom components */
   events?: Partial<NodeEventsHandler<CustomEvents>>
+
+  ariaLabel?: string
 }
 
 export interface GraphNode<Data = ElementData, CustomEvents extends Record<string, CustomEvent> = any>

packages/core/src/types/store.ts

@@ -87,6 +87,8 @@ export interface State extends Omit<FlowOptions, 'id' | 'modelValue'> {
 
   edgesUpdatable: EdgeUpdatable
   edgesFocusable: boolean
+
+  nodesFocusable: boolean
   nodesDraggable: boolean
   nodesConnectable: boolean
 
@@ -119,6 +121,8 @@ export interface State extends Omit<FlowOptions, 'id' | 'modelValue'> {
 
   disableKeyboardA11y: boolean
 
+  ariaLiveMessage: string
+
   /** current vue flow version you're using */
   readonly vueFlowVersion: string
 }

packages/core/src/utils/a11y.ts

@@ -1,4 +1,13 @@
+import type { XYPosition } from '~/types'
+
 export const ARIA_NODE_DESC_KEY = 'vue-flow__node-desc'
 export const ARIA_EDGE_DESC_KEY = 'vue-flow__edge-desc'
 
 export const elementSelectionKeys = ['Enter', ' ', 'Escape']
+
+export const arrowKeyDiffs: Record<string, XYPosition> = {
+  ArrowUp: { x: 0, y: -1 },
+  ArrowDown: { x: 0, y: 1 },
+  ArrowLeft: { x: -1, y: 0 },
+  ArrowRight: { x: 1, y: 0 },
+}

packages/core/src/utils/drag.ts

@@ -26,7 +26,8 @@ export function getDragItems(
     .map((n) =>
       markRaw({
         id: n.id,
-        position: n.computedPosition || { x: 0, y: 0, z: 0 },
+        position: n.position || { x: 0, y: 0 },
+        computedPosition: n.computedPosition || { x: 0, y: 0, z: 1 },
         distance: {
           x: mousePos.x - n.computedPosition?.x || 0,
           y: mousePos.y - n.computedPosition?.y || 0,
@@ -59,7 +60,7 @@ export function getEventHandlerParams({
   return [id ? extendedDragItems.find((n) => n.id === id)! : extendedDragItems[0], extendedDragItems]
 }
 
-export function applyExtent<T extends NodeDragItem | GraphNode>(item: T, extent?: CoordinateExtent, parent?: GraphNode) {
+export function getExtent<T extends NodeDragItem | GraphNode>(item: T, extent?: CoordinateExtent, parent?: GraphNode) {
   let currentExtent = item.extent || extent
 
   if (item.extent === 'parent') {
@@ -95,3 +96,28 @@ export function applyExtent<T extends NodeDragItem | GraphNode>(item: T, extent?
 
   return currentExtent as CoordinateExtent
 }
+export const calcNextPosition = (
+  node: GraphNode | NodeDragItem,
+  nextPosition: XYPosition,
+  nodeExtent?: CoordinateExtent,
+  parentNode?: GraphNode,
+) => {
+  const extent = getExtent(node, nodeExtent, parentNode)
+
+  const clampedPos = clampPosition(nextPosition, extent)
+
+  const parentPosition = { x: 0, y: 0 }
+
+  if (parentNode) {
+    parentPosition.x = parentNode.computedPosition.x
+    parentPosition.y = parentNode.computedPosition.y
+  }
+
+  return {
+    position: {
+      x: clampedPos.x - parentPosition.x,
+      y: clampedPos.y - parentPosition.y,
+    },
+    computedPosition: clampedPos,
+  }
+}

packages/core/src/utils/graph.ts

@@ -89,6 +89,7 @@ export const parseNode = (node: Node, nodeExtent: CoordinateExtent, defaults?: P
       draggable: undefined,
       selectable: undefined,
       connectable: undefined,
+      focusable: undefined,
       selected: false,
       dragging: false,
       resizing: false,
@@ -125,6 +126,7 @@ export const parseEdge = (edge: Edge, defaults?: Partial<GraphEdge>): GraphEdge
         targetY: 0 || defaults?.targetY,
         updatable: edge.updatable ?? defaults?.updatable,
         selectable: edge.selectable ?? defaults?.selectable,
+        focusable: edge.focusable ?? defaults?.focusable,
         data,
         events: markRaw(events),
         label: (edge.label && !isString(edge.label) ? markRaw(edge.label) : edge.label) || defaults?.label,
@@ -369,6 +371,6 @@ export const getMarkerId = (marker: EdgeMarkerType | undefined, vueFlowId?: stri
 
   return `${idPrefix}${Object.keys(marker)
     .sort()
-    .map((key: string) => `${key}=${marker[<keyof EdgeMarkerType>key]}`)
+    .map((key) => `${key}=${marker[<keyof EdgeMarkerType>key]}`)
     .join('&')}`
 }

packages/core/src/utils/node.ts

@@ -30,12 +30,13 @@ export const handleNodeClick = (
   addSelectedNodes: Actions['addSelectedNodes'],
   removeSelectedElements: Actions['removeSelectedElements'],
   nodesSelectionActive: Ref<boolean>,
+  unselect = false,
 ) => {
   nodesSelectionActive.value = false
 
   if (!node.selected) {
     addSelectedNodes([node])
-  } else if (node.selected && multiSelectionActive) {
+  } else if (unselect || (node.selected && multiSelectionActive)) {
     removeSelectedElements([node])
   }
 }