svelte-dnd-action 0.9.76 → 0.9.78

package/README.md

@@ -1,7 +1,5 @@
 # SVELTE DND ACTION [![Known Vulnerabilities](https://snyk.io/test/github/isaacHagoel/svelte-dnd-action/badge.svg?targetFile=package.json)](https://snyk.io/test/github/isaacHagoel/svelte-dnd-action?targetFile=package.json)
 
-> Shameless plug: If you are making AI Apps check out my brand-new, open source [dev tool](https://github.com/pragmaticfish/sushify)
-
 This is a feature-complete implementation of drag and drop for Svelte using a custom action. It supports almost every imaginable drag and drop use-case, any input device and is fully accessible. <br />
 It requires very minimal configuration, while offering a rich set of primitives that allow overriding basically any of its default behaviours (using the handler functions). <br /><br />
 See full features list below. <br />
@@ -118,7 +116,7 @@ An options-object with the following attributes:
 | `dropTargetStyle` | Object&lt;String&gt; | No | `{outline: 'rgba(255, 255, 102, 0.7) solid 2px'}` | An object of styles to apply to the dnd-zone when items can be dragged into it. Note: the styles override any inline styles applied to the dnd-zone. When the styles are removed, any original inline styles will be lost |
 | `dropTargetClasses`| Array&lt;String&gt; | No | `[]` | A list of classes to apply to the dnd-zone when items can be dragged into it. Note: make sure the classes you use are global. |
 | `transformDraggedElement` | Function | No | `() => {}` | A function that is invoked when the draggable element enters the dnd-zone or hover overs a new index in the current dnd-zone. <br />Signature:<br />function(element, data, index) {}<br />**element**: The dragged element. <br />**data**: The data of the item from the items array.<br />**index**: The index the dragged element will become in the new dnd-zone.<br /><br />This allows you to override properties on the dragged element, such as innerHTML to change how it displays. If what you are after is altering styles, do it to the children, not to the dragged element itself |
-| `autoAriaDisabled` | Boolean | No | `false` | Setting it to true will disable all the automatically added aria attributes and aria alerts (for example when the user starts/ stops dragging using the keyboard).<br /> **Use it only if you intend to implement your own custom instructions, roles and alerts.** In such a case, you might find the exported function `alertToScreenReader(string)` useful. |
+| `autoAriaDisabled` | Boolean | No | `false` | Setting it to true will disable all the automatically added aria attributes and aria alerts (for example when the user starts/ stops dragging using the keyboard).<br /> **Use it only if you intend to implement your own custom instructions, roles and alerts.** In such a case, you might find the exported function `alertToScreenReader(string)` useful. <br />**If you only want to change the wording (ex: to translate it), use `setAriaStrings` instead and leave this off.** |
 | `centreDraggedOnCursor` | Boolean | No | `false` | Setting it to true will cause elements from this dnd-zone to position their center on the cursor on drag start, effectively turning the cursor to the focal point that triggers all the dnd events (ex: entering another zone). Useful for dnd-zones with large items that can be dragged over small items. |
 | `useCursorForDetection` | Boolean | No | `false` | Setting it to true will use the cursor position instead of the dragged element's center for drop zone detection. This improves accuracy when dragging large elements over small drop targets. Unlike `centreDraggedOnCursor`, this option does not reposition the dragged element. |
 | `dropAnimationDisabled` | Boolean | No | `false` | Setting it to true will disable the animation of the dropped element to its final place. |
@@ -167,13 +165,74 @@ If you don't provide the aria-labels everything will still work, but the message
 _Note_: in general you probably want to use semantic-html (ex: `ol` and `li` elements rather than `section` and `div`) but the library is screen readers friendly regardless (or at least that's the goal :)).
 If you want to implement your own custom screen-reader alerts, roles and instructions, you can use the `autoAriaDisabled` options and wire everything up yourself using markup and the `consider` and `finalize` handlers (for example: [unsortable list](https://svelte.dev/playground/e020ea1051dc4ae3ac2b697064f234bc?version=3)).
 
+#### Choosing the keyboard drag trigger
+
+By default both _Space_ and _Enter_ start and stop a keyboard drag. If your app needs one of
+those keys for something else - ex: _Enter_ to open or edit the focused item - narrow the trigger:
+
+```javascript
+import {setKeyboardDragTrigger} from "svelte-dnd-action";
+
+setKeyboardDragTrigger("space");
+```
+
+Accepted values are `"space"`, `"enter"` and `"space_or_enter"` (the default). Pass `null` or
+`undefined` (or call with no argument) to restore the default. Any other value throws.
+
+Keys outside the trigger are never claimed. _Escape_ still ends a drag under every trigger.
+
+The setting is global to the document and applies to every dndzone; different zones cannot use
+different triggers at the same time. It can be called at any time, including after the zones have
+rendered. The built-in screen-reader instruction follows it automatically.
+
+#### Translating the screen-reader messages
+
+`autoAriaDisabled` disables all automatically added ARIA attributes, roles, instructions and alerts. If you only want to translate the screen-reader wording, import `setAriaStrings` and leave `autoAriaDisabled` off:
+
+```javascript
+import {setAriaStrings} from "svelte-dnd-action";
+
+const instructionsParTouche = {
+    space: `Tabulez jusqu'à un élément et appuyez sur espace pour le déplacer`,
+    enter: `Tabulez jusqu'à un élément et appuyez sur entrée pour le déplacer`,
+    space_or_enter: `Tabulez jusqu'à un élément et appuyez sur espace ou entrée pour le déplacer`
+};
+
+setAriaStrings({
+    dragStarted: ({itemLabel, zoneLabel, canMoveBetweenZones}) =>
+        `Déplacement de ${itemLabel} commencé. Utilisez les flèches pour le déplacer dans la liste ${zoneLabel}` +
+        (canMoveBetweenZones ? `, ou tabulez vers une autre liste` : ``),
+    movedToPosition: ({itemLabel, zoneLabel, position}) => `${itemLabel} déplacé en position ${position} dans la liste ${zoneLabel}`,
+    movedToZoneEnd: ({itemLabel, zoneLabel}) => `${itemLabel} déplacé à la fin de la liste ${zoneLabel}`,
+    movedToZoneStart: ({itemLabel, zoneLabel}) => `${itemLabel} déplacé au début de la liste ${zoneLabel}`,
+    // The default message omits the destination, but custom messages can include it
+    dropped: ({itemLabel, zoneLabel, position, count}) => `${itemLabel} déposé dans ${zoneLabel}, ${position} sur ${count}`,
+    zoneActiveInstruction: ({keyboardDragTrigger}) => instructionsParTouche[keyboardDragTrigger],
+    zoneDragDisabledInstruction: `Cette liste de glisser-déposer est désactivée`
+});
+```
+
+Every key is optional. Omitted keys use their English defaults. The five announcement keys are formatter
+functions, so translations can control word order and pluralisation. Each formatter receives `itemLabel`
+and `zoneLabel` from the consumer-provided `aria-label` attributes, plus `position` and `count` for the
+item's 1-based position and the number of items in the relevant zone. `dragStarted` also receives
+`canMoveBetweenZones`. Destructure only the fields your wording needs; the built-in English messages do not
+use every field, but custom messages can.
+
+`zoneActiveInstruction` takes a string or a formatter receiving the value set through
+[`setKeyboardDragTrigger`](#choosing-the-keyboard-drag-trigger).
+
+Call `setAriaStrings` during app-level initialization and again whenever the application locale changes. Each call defines the complete active locale by applying its overrides to the English defaults, so omitted keys return to English rather than retaining values from the previous locale. Existing instruction elements update immediately. Pass `null` to restore all English defaults. Unknown keys and values of the wrong type throw an error.
+
+The setting is global to the document and applies to every dndzone. Different zones cannot use different strings at the same time.
+
 ##### Keyboard support
 
 -   Tab into a dnd container to get a description and instructions
--   Tab into an item and press the _Space_/_Enter_ key to enter dragging-mode. The reader will tell the user a drag has started.
+-   Tab into an item and press the _Space_/_Enter_ key to enter dragging-mode (see `setKeyboardDragTrigger` to narrow this to one key). The reader will tell the user a drag has started.
 -   Use the _arrow keys_ while in dragging-mode to change the item's position in the list (down and right are the same, up and left are the same). The reader will tell the user about position changes.
 -   Tab to another dnd container while in dragging-mode in order to move the item to it (the item will be moved to it when it gets focus). The reader will tell the user that item was added to the new list.
--   Press _Space_/_Enter_ key while focused on an item, or the _Escape_ key anywhere to exit dragging mode. The reader will tell the user that they are no longer dragging.
+-   Press the drag-trigger key while focused on an item, or the _Escape_ key anywhere to exit dragging mode. The reader will tell the user that they are no longer dragging.
 -   Clicking on another item while in drag mode will make it the new drag target. Clicking outside of any draggable will exit dragging-mode (and tell the user)
 -   Mouse drag and drop can be preformed independently of keyboard dragging (as in an item can be dragged with the mouse while in or out of keyboard initiated dragging-mode)
 -   Keyboard drag uses the same `consider` (only on drag start) and `finalize` (every time the item is moved) events but share only some of the `TRIGGERS`. The same handlers should work fine for both.

package/dist/index.d.ts

@@ -82,6 +82,36 @@ export interface DndZoneAttributes<T> {
  */
 export declare function alertToScreenReader(txt: string): void;
 
+// Every message key receives the same core context - itemLabel, zoneLabel, position, count -
+// so a consumer can word any of them positionally. Only dragStarted carries an extra.
+export interface AriaStrings {
+    dragStarted?: (ctx: {itemLabel: string; zoneLabel: string; position: number; count: number; canMoveBetweenZones: boolean}) => string;
+    movedToPosition?: (ctx: {itemLabel: string; zoneLabel: string; position: number; count: number}) => string;
+    movedToZoneEnd?: (ctx: {itemLabel: string; zoneLabel: string; position: number; count: number}) => string;
+    movedToZoneStart?: (ctx: {itemLabel: string; zoneLabel: string; position: number; count: number}) => string;
+    dropped?: (ctx: {itemLabel: string; zoneLabel: string; position: number; count: number}) => string;
+    zoneActiveInstruction?: string | ((ctx: {keyboardDragTrigger: "space" | "enter" | "space_or_enter"}) => string);
+    zoneDragDisabledInstruction?: string;
+}
+
+/**
+ * Overrides the strings the library speaks to screen readers. Merges over the built-in English defaults,
+ * so each call describes a whole locale rather than patching the previous one - anything a call leaves
+ * out goes back to English.
+ * This is global and applies to all dndzones.
+ * Pass null to restore the built-in English strings.
+ */
+export declare function setAriaStrings(overrides: AriaStrings | null): void;
+
+/**
+ * Chooses which key(s) start and stop a keyboard drag on a focused item. Keys outside the trigger are left
+ * completely untouched by the library, so the app can use them - ex: "space" keeps Enter free to activate the
+ * focused item. This is global and applies to all dndzones. It can be called at any time.
+ * Pass null or undefined (or call with no argument) to restore the default, "space_or_enter".
+ * @throws {Error} if given anything other than the documented values, null, or undefined
+ */
+export declare function setKeyboardDragTrigger(trigger?: "space" | "enter" | "space_or_enter" | null): void;
+
 /**
  * Allows using another key instead of "id" in the items data. This is global and applies to all dndzones.
  * Has to be called when there are no rendered dndzones whatsoever.

package/dist/index.js

@@ -293,6 +293,24 @@
     POINTER: "pointer",
     KEYBOARD: "keyboard"
   };
+
+  // Maps each valid global keyboardDragTrigger value (see setKeyboardDragTrigger) to the
+  // KeyboardEvent.key values it covers. Keys that are not part of the active trigger are left
+  // completely untouched by the library.
+  var KEYBOARD_DRAG_TRIGGER_KEYS = {
+    space: [" "],
+    enter: ["Enter"],
+    space_or_enter: [" ", "Enter"]
+  };
+  var DEFAULT_KEYBOARD_DRAG_TRIGGER = "space_or_enter";
+
+  // Human-readable phrase for each trigger, used by the default screen-reader instruction (see
+  // src/helpers/aria.js). Must have exactly the same keys as KEYBOARD_DRAG_TRIGGER_KEYS above.
+  var KEYBOARD_DRAG_TRIGGER_PHRASES = {
+    space: "space-bar",
+    enter: "enter",
+    space_or_enter: "space-bar or enter"
+  };
   var SHADOW_ITEM_MARKER_PROPERTY_NAME = "isDndShadowItem";
   var SHADOW_ELEMENT_ATTRIBUTE_NAME = "data-is-dnd-shadow-item-internal";
   var SHADOW_ELEMENT_HINT_ATTRIBUTE_NAME = "data-is-dnd-shadow-item-hint";
@@ -2207,12 +2225,54 @@
     };
   }
 
-  var _ID_TO_INSTRUCTION;
+  var _INSTRUCTION_ID_TO_ST;
   var INSTRUCTION_IDs$1 = {
     DND_ZONE_ACTIVE: "dnd-zone-active",
     DND_ZONE_DRAG_DISABLED: "dnd-zone-drag-disabled"
   };
-  var ID_TO_INSTRUCTION = (_ID_TO_INSTRUCTION = {}, _defineProperty(_ID_TO_INSTRUCTION, INSTRUCTION_IDs$1.DND_ZONE_ACTIVE, "Tab to one the items and press space-bar or enter to start dragging it"), _defineProperty(_ID_TO_INSTRUCTION, INSTRUCTION_IDs$1.DND_ZONE_DRAG_DISABLED, "This is a disabled drag and drop list"), _ID_TO_INSTRUCTION);
+  var INSTRUCTION_ID_TO_STRING_KEY = (_INSTRUCTION_ID_TO_ST = {}, _defineProperty(_INSTRUCTION_ID_TO_ST, INSTRUCTION_IDs$1.DND_ZONE_ACTIVE, "zoneActiveInstruction"), _defineProperty(_INSTRUCTION_ID_TO_ST, INSTRUCTION_IDs$1.DND_ZONE_DRAG_DISABLED, "zoneDragDisabledInstruction"), _INSTRUCTION_ID_TO_ST);
+  var DEFAULT_ARIA_STRINGS = {
+    dragStarted: function dragStarted(_ref) {
+      var itemLabel = _ref.itemLabel,
+        zoneLabel = _ref.zoneLabel,
+        canMoveBetweenZones = _ref.canMoveBetweenZones;
+      return "Started dragging item ".concat(itemLabel, ". Use the arrow keys to move it within its list ").concat(zoneLabel) + (canMoveBetweenZones ? ", or tab to another list in order to move the item into it" : "");
+    },
+    movedToPosition: function movedToPosition(_ref2) {
+      var itemLabel = _ref2.itemLabel,
+        zoneLabel = _ref2.zoneLabel,
+        position = _ref2.position;
+      return "Moved item ".concat(itemLabel, " to position ").concat(position, " in the list ").concat(zoneLabel);
+    },
+    movedToZoneEnd: function movedToZoneEnd(_ref3) {
+      var itemLabel = _ref3.itemLabel,
+        zoneLabel = _ref3.zoneLabel;
+      return "Moved item ".concat(itemLabel, " to the end of the list ").concat(zoneLabel);
+    },
+    movedToZoneStart: function movedToZoneStart(_ref4) {
+      var itemLabel = _ref4.itemLabel,
+        zoneLabel = _ref4.zoneLabel;
+      return "Moved item ".concat(itemLabel, " to the beginning of the list ").concat(zoneLabel);
+    },
+    dropped: function dropped(_ref5) {
+      var itemLabel = _ref5.itemLabel;
+      return "Stopped dragging item ".concat(itemLabel);
+    },
+    zoneActiveInstruction: function zoneActiveInstruction(_ref6) {
+      var keyboardDragTrigger = _ref6.keyboardDragTrigger;
+      return "Tab to one the items and press ".concat(KEYBOARD_DRAG_TRIGGER_PHRASES[keyboardDragTrigger], " to start dragging it");
+    },
+    zoneDragDisabledInstruction: "This is a disabled drag and drop list"
+  };
+  var FUNCTION_ARIA_STRING_KEYS = ["dragStarted", "movedToPosition", "movedToZoneEnd", "movedToZoneStart", "dropped"];
+  // zoneActiveInstruction names the key that starts a drag, so a translation may need to vary it with the trigger.
+  var STRING_OR_FUNCTION_ARIA_STRING_KEYS = ["zoneActiveInstruction"];
+  // zoneDragDisabledInstruction has no drag to start and thus no key to name, so it stays string-only.
+  var STRING_ONLY_ARIA_STRING_KEYS = ["zoneDragDisabledInstruction"];
+  var ariaStrings = _objectSpread2({}, DEFAULT_ARIA_STRINGS);
+  var instructionCtx = {
+    keyboardDragTrigger: DEFAULT_KEYBOARD_DRAG_TRIGGER
+  };
   var ALERT_DIV_ID = "dnd-action-aria-alert";
   var alertsDiv;
   function initAriaOnBrowser() {
@@ -2238,11 +2298,11 @@
     document.body.prepend(alertsDiv);
 
     // setting the instructions
-    Object.entries(ID_TO_INSTRUCTION).forEach(function (_ref) {
-      var _ref2 = _slicedToArray(_ref, 2),
-        id = _ref2[0],
-        txt = _ref2[1];
-      return document.body.prepend(instructionToHiddenDiv(id, txt));
+    Object.entries(INSTRUCTION_ID_TO_STRING_KEY).forEach(function (_ref7) {
+      var _ref8 = _slicedToArray(_ref7, 2),
+        id = _ref8[0],
+        key = _ref8[1];
+      return document.body.prepend(instructionToHiddenDiv(id, formatWithFallback(key, instructionCtx)));
     });
   }
 
@@ -2265,7 +2325,7 @@
    */
   function destroyAria() {
     if (isOnServer || !alertsDiv) return;
-    Object.keys(ID_TO_INSTRUCTION).forEach(function (id) {
+    Object.keys(INSTRUCTION_ID_TO_STRING_KEY).forEach(function (id) {
       var _document$getElementB;
       return (_document$getElementB = document.getElementById(id)) === null || _document$getElementB === void 0 ? void 0 : _document$getElementB.remove();
     });
@@ -2275,12 +2335,18 @@
   function instructionToHiddenDiv(id, txt) {
     var div = document.createElement("div");
     div.id = id;
-    div.innerHTML = "<p>".concat(txt, "</p>");
+    renderInstruction(div, txt);
     div.style.display = "none";
     div.style.position = "fixed";
     div.style.zIndex = "-5";
     return div;
   }
+  function renderInstruction(div, txt) {
+    div.replaceChildren();
+    var paragraph = document.createElement("p");
+    paragraph.textContent = txt;
+    div.appendChild(paragraph);
+  }
 
   /**
    * Will make the screen reader alert the provided text to the user
@@ -2299,6 +2365,133 @@
     alertsDiv.style.display = "inline";
   }
 
+  /**
+   * Overrides the strings the library announces to screen readers. Each call starts with the built-in
+   * English defaults and applies the supplied overrides, so omitted keys return to English when the locale
+   * changes. Existing instruction elements update immediately. This setting is global to all dndzones.
+   * Pass null to restore the built-in English strings.
+   * @param {Object | null} overrides - any subset of: dragStarted, movedToPosition, movedToZoneEnd,
+   * movedToZoneStart, dropped (functions taking a context object and returning a string);
+   * zoneActiveInstruction (a string, or a function taking {keyboardDragTrigger} and returning a string -
+   * useful because a hard-coded translation can't name the right key if the app varies the trigger);
+   * zoneDragDisabledInstruction (a string only - a disabled zone has no drag to start, so there is no key
+   * for a formatter to name)
+   * @throws {Error} if overrides is not an object or null, contains an unknown key, or contains a value of
+   * the wrong type. Validation completes before the active strings change.
+   */
+  function setAriaStrings(overrides) {
+    if (overrides === null || overrides === undefined) {
+      ariaStrings = _objectSpread2({}, DEFAULT_ARIA_STRINGS);
+    } else {
+      if (_typeof(overrides) !== "object" || Array.isArray(overrides)) {
+        throw new Error("setAriaStrings expects an object or null but instead got a ".concat(_typeof(overrides), ", ").concat(toString(overrides)));
+      }
+      Object.keys(overrides).forEach(function (key) {
+        if (!Object.prototype.hasOwnProperty.call(DEFAULT_ARIA_STRINGS, key)) {
+          throw new Error("Can't set non existing aria string ".concat(key, "! Supported strings: ").concat(Object.keys(DEFAULT_ARIA_STRINGS)));
+        }
+        var value = overrides[key];
+        if (FUNCTION_ARIA_STRING_KEYS.includes(key) && typeof value !== "function") {
+          throw new Error("".concat(key, " should be a function but instead it is a ").concat(_typeof(value), ", ").concat(toString(value)));
+        }
+        if (STRING_OR_FUNCTION_ARIA_STRING_KEYS.includes(key) && typeof value !== "string" && typeof value !== "function") {
+          throw new Error("".concat(key, " should be a string or a function but instead it is a ").concat(_typeof(value), ", ").concat(toString(value)));
+        }
+        if (STRING_ONLY_ARIA_STRING_KEYS.includes(key) && typeof value !== "string") {
+          throw new Error("".concat(key, " should be a string but instead it is a ").concat(_typeof(value), ", ").concat(toString(value)));
+        }
+      });
+      ariaStrings = _objectSpread2(_objectSpread2({}, DEFAULT_ARIA_STRINGS), overrides);
+    }
+    refreshInstructions();
+  }
+  function formatAriaString(strings, key, ctx) {
+    var ariaString = strings[key];
+    return typeof ariaString === "function" ? ariaString(ctx) : ariaString;
+  }
+  function formatWithFallback(key, ctx) {
+    try {
+      return formatAriaString(ariaStrings, key, ctx);
+    } catch (err) {
+      printDebug(function () {
+        return ["aria string formatter for \"".concat(key, "\" threw, falling back to the default"), err];
+      });
+      try {
+        return formatAriaString(DEFAULT_ARIA_STRINGS, key, ctx);
+      } catch (defaultErr) {
+        printDebug(function () {
+          return ["default aria string formatter for \"".concat(key, "\" also threw"), defaultErr];
+        });
+        return "";
+      }
+    }
+  }
+  function refreshInstructions() {
+    if (isOnServer) return;
+    Object.entries(INSTRUCTION_ID_TO_STRING_KEY).forEach(function (_ref9) {
+      var _ref10 = _slicedToArray(_ref9, 2),
+        id = _ref10[0],
+        key = _ref10[1];
+      var div = document.getElementById(id);
+      if (div) renderInstruction(div, formatWithFallback(key, instructionCtx));
+    });
+  }
+
+  /**
+   * Sets the context the static instruction formatters receive, and re-renders them. Internal - the
+   * public entry point is setKeyboardDragTrigger.
+   * @param {{keyboardDragTrigger: "space"|"enter"|"space_or_enter"}} ctx
+   */
+  function setInstructionContext(ctx) {
+    instructionCtx = _objectSpread2({}, ctx);
+    refreshInstructions();
+  }
+
+  /**
+   * Formats and announces one configured ARIA message. If a consumer formatter throws, the built-in
+   * English formatter is used and the error is reported through printDebug. Formatter errors must not
+   * escape because this function runs during the drag lifecycle.
+   * @param {string} key - one of the keys accepted by setAriaStrings
+   * @param {Object} [ctx] - the interpolation context for that key
+   */
+  function announceToScreenReader(key, ctx) {
+    alertToScreenReader(formatWithFallback(key, ctx));
+  }
+
+  var activeTrigger = DEFAULT_KEYBOARD_DRAG_TRIGGER;
+
+  /**
+   * Chooses which key(s) start and stop a keyboard drag on a focused item. Keys outside the trigger are
+   * left completely untouched by the library (no preventDefault, no stopPropagation), so the app can use
+   * them - ex: "space" keeps Enter free to activate the focused item.
+   * This setting is global to the document and applies to every dndzone. It can be called at any time.
+   * Pass null or undefined (or call with no argument) to restore the default, "space_or_enter".
+   * @param {"space"|"enter"|"space_or_enter"|null|undefined} [trigger]
+   * @throws {Error} if given anything other than the documented values, null, or undefined
+   */
+  function setKeyboardDragTrigger(trigger) {
+    if (trigger === null || trigger === undefined) {
+      activeTrigger = DEFAULT_KEYBOARD_DRAG_TRIGGER;
+    } else if (typeof trigger !== "string" || !Object.prototype.hasOwnProperty.call(KEYBOARD_DRAG_TRIGGER_KEYS, trigger)) {
+      throw new Error("setKeyboardDragTrigger expects one of ".concat(Object.keys(KEYBOARD_DRAG_TRIGGER_KEYS).map(function (key) {
+        return "\"".concat(key, "\"");
+      }).join(", "), " or null but instead got a ").concat(_typeof(trigger), ", ").concat(toString(trigger)));
+    } else {
+      activeTrigger = trigger;
+    }
+    setInstructionContext({
+      keyboardDragTrigger: activeTrigger
+    });
+  }
+
+  /**
+   * @param {string} key - a KeyboardEvent.key value
+   * @return {boolean} whether this key starts/stops a drag under the active trigger
+   */
+  function isKeyboardDragTriggerKey(key) {
+    return KEYBOARD_DRAG_TRIGGER_KEYS[activeTrigger].includes(key);
+  }
+
   var DEFAULT_DROP_ZONE_TYPE = "--any--";
   var DEFAULT_DROP_TARGET_STYLE = {
     outline: "rgba(255, 255, 102, 0.7) solid 2px"
@@ -2428,12 +2621,22 @@
     if (newlyFocusedDz.getBoundingClientRect().top < focusedDz.getBoundingClientRect().top || newlyFocusedDz.getBoundingClientRect().left < focusedDz.getBoundingClientRect().left) {
       targetItems.push(itemToMove);
       if (!autoAriaDisabled) {
-        alertToScreenReader("Moved item ".concat(focusedItemLabel, " to the end of the list ").concat(focusedDzLabel));
+        announceToScreenReader("movedToZoneEnd", {
+          itemLabel: focusedItemLabel,
+          zoneLabel: focusedDzLabel,
+          position: targetItems.length,
+          count: targetItems.length
+        });
       }
     } else {
       targetItems.unshift(itemToMove);
       if (!autoAriaDisabled) {
-        alertToScreenReader("Moved item ".concat(focusedItemLabel, " to the beginning of the list ").concat(focusedDzLabel));
+        announceToScreenReader("movedToZoneStart", {
+          itemLabel: focusedItemLabel,
+          zoneLabel: focusedDzLabel,
+          position: 1,
+          count: targetItems.length
+        });
       }
     }
     var dzFrom = focusedDz;
@@ -2470,7 +2673,17 @@
     var droppedItemType = draggedItemType;
     if (!droppedConfig) return;
     if (!droppedConfig.autoAriaDisabled) {
-      alertToScreenReader("Stopped dragging item ".concat(focusedItemLabel));
+      // Include the destination and final position so localized messages can describe the completed drop.
+      var droppedItems = droppedConfig.items;
+      var droppedIdx = droppedItems.findIndex(function (item) {
+        return item[ITEM_ID_KEY] === droppedItemId;
+      });
+      announceToScreenReader("dropped", {
+        itemLabel: focusedItemLabel,
+        zoneLabel: focusedDzLabel,
+        position: (droppedIdx < 0 ? 0 : droppedIdx) + 1,
+        count: droppedItems.length
+      });
     }
     if (allDragTargets.has(document.activeElement)) {
       document.activeElement.blur();
@@ -2527,6 +2740,10 @@
         case "Enter":
         case " ":
           {
+            // keys outside the configured trigger belong to the consumer - don't claim them in any way
+            if (!isKeyboardDragTriggerKey(e.key)) {
+              return;
+            }
             // we don't want to affect nested input elements or clickable elements
             if ((e.target.disabled !== undefined || e.target.href || e.target.isContentEditable) && !allDragTargets.has(e.target)) {
               return;
@@ -2557,7 +2774,12 @@
             });
             if (idx < children.length - 1) {
               if (!config.autoAriaDisabled) {
-                alertToScreenReader("Moved item ".concat(focusedItemLabel, " to position ").concat(idx + 2, " in the list ").concat(focusedDzLabel));
+                announceToScreenReader("movedToPosition", {
+                  itemLabel: focusedItemLabel,
+                  zoneLabel: focusedDzLabel,
+                  position: idx + 2,
+                  count: items.length
+                });
               }
               swap(items, idx, idx + 1);
               dispatchFinalizeEvent(node, items, {
@@ -2583,7 +2805,12 @@
             });
             if (_idx > 0) {
               if (!config.autoAriaDisabled) {
-                alertToScreenReader("Moved item ".concat(focusedItemLabel, " to position ").concat(_idx, " in the list ").concat(focusedDzLabel));
+                announceToScreenReader("movedToPosition", {
+                  itemLabel: focusedItemLabel,
+                  zoneLabel: focusedDzLabel,
+                  position: _idx,
+                  count: _items.length
+                });
               }
               swap(_items, _idx, _idx - 1);
               dispatchFinalizeEvent(node, _items, {
@@ -2614,11 +2841,18 @@
         return dzToConfig.get(dz).dropTargetClasses;
       });
       if (!config.autoAriaDisabled) {
-        var msg = "Started dragging item ".concat(focusedItemLabel, ". Use the arrow keys to move it within its list ").concat(focusedDzLabel);
-        if (dropTargets.length > 1) {
-          msg += ", or tab to another list in order to move the item into it";
-        }
-        alertToScreenReader(msg);
+        // Include the starting position so localized messages can describe where the item was picked up.
+        var startItems = dzToConfig.get(node).items;
+        var startIdx = startItems.findIndex(function (item) {
+          return item[ITEM_ID_KEY] === focusedItemId;
+        });
+        announceToScreenReader("dragStarted", {
+          itemLabel: focusedItemLabel,
+          zoneLabel: focusedDzLabel,
+          position: (startIdx < 0 ? 0 : startIdx) + 1,
+          count: startItems.length,
+          canMoveBetweenZones: dropTargets.length > 1
+        });
       }
       dispatchConsiderEvent(node, dzToConfig.get(node).items, {
         trigger: TRIGGERS.DRAG_STARTED,
@@ -2995,7 +3229,7 @@
       window.addEventListener("touchend", resetStartDrag);
     }
     function handleKeyDown(e) {
-      if (e.key === "Enter" || e.key === " ") isItemsDragDisabled.set(false);
+      if (isKeyboardDragTriggerKey(e.key)) isItemsDragDisabled.set(false);
     }
     function resetStartDrag() {
       isItemsDragDisabled.set(true);
@@ -3043,8 +3277,10 @@
   exports.dragHandle = dragHandle;
   exports.dragHandleZone = dragHandleZone;
   exports.overrideItemIdKeyNameBeforeInitialisingDndZones = overrideItemIdKeyNameBeforeInitialisingDndZones;
+  exports.setAriaStrings = setAriaStrings;
   exports.setDebugMode = setDebugMode;
   exports.setFeatureFlag = setFeatureFlag;
+  exports.setKeyboardDragTrigger = setKeyboardDragTrigger;
 
   Object.defineProperty(exports, '__esModule', { value: true });
 

package/dist/index.mjs

@@ -287,6 +287,24 @@ var SOURCES = {
   POINTER: "pointer",
   KEYBOARD: "keyboard"
 };
+
+// Maps each valid global keyboardDragTrigger value (see setKeyboardDragTrigger) to the
+// KeyboardEvent.key values it covers. Keys that are not part of the active trigger are left
+// completely untouched by the library.
+var KEYBOARD_DRAG_TRIGGER_KEYS = {
+  space: [" "],
+  enter: ["Enter"],
+  space_or_enter: [" ", "Enter"]
+};
+var DEFAULT_KEYBOARD_DRAG_TRIGGER = "space_or_enter";
+
+// Human-readable phrase for each trigger, used by the default screen-reader instruction (see
+// src/helpers/aria.js). Must have exactly the same keys as KEYBOARD_DRAG_TRIGGER_KEYS above.
+var KEYBOARD_DRAG_TRIGGER_PHRASES = {
+  space: "space-bar",
+  enter: "enter",
+  space_or_enter: "space-bar or enter"
+};
 var SHADOW_ITEM_MARKER_PROPERTY_NAME = "isDndShadowItem";
 var SHADOW_ELEMENT_ATTRIBUTE_NAME = "data-is-dnd-shadow-item-internal";
 var SHADOW_ELEMENT_HINT_ATTRIBUTE_NAME = "data-is-dnd-shadow-item-hint";
@@ -2201,12 +2219,54 @@ function dndzone$2(node, options) {
   };
 }
 
-var _ID_TO_INSTRUCTION;
+var _INSTRUCTION_ID_TO_ST;
 var INSTRUCTION_IDs$1 = {
   DND_ZONE_ACTIVE: "dnd-zone-active",
   DND_ZONE_DRAG_DISABLED: "dnd-zone-drag-disabled"
 };
-var ID_TO_INSTRUCTION = (_ID_TO_INSTRUCTION = {}, _defineProperty(_ID_TO_INSTRUCTION, INSTRUCTION_IDs$1.DND_ZONE_ACTIVE, "Tab to one the items and press space-bar or enter to start dragging it"), _defineProperty(_ID_TO_INSTRUCTION, INSTRUCTION_IDs$1.DND_ZONE_DRAG_DISABLED, "This is a disabled drag and drop list"), _ID_TO_INSTRUCTION);
+var INSTRUCTION_ID_TO_STRING_KEY = (_INSTRUCTION_ID_TO_ST = {}, _defineProperty(_INSTRUCTION_ID_TO_ST, INSTRUCTION_IDs$1.DND_ZONE_ACTIVE, "zoneActiveInstruction"), _defineProperty(_INSTRUCTION_ID_TO_ST, INSTRUCTION_IDs$1.DND_ZONE_DRAG_DISABLED, "zoneDragDisabledInstruction"), _INSTRUCTION_ID_TO_ST);
+var DEFAULT_ARIA_STRINGS = {
+  dragStarted: function dragStarted(_ref) {
+    var itemLabel = _ref.itemLabel,
+      zoneLabel = _ref.zoneLabel,
+      canMoveBetweenZones = _ref.canMoveBetweenZones;
+    return "Started dragging item ".concat(itemLabel, ". Use the arrow keys to move it within its list ").concat(zoneLabel) + (canMoveBetweenZones ? ", or tab to another list in order to move the item into it" : "");
+  },
+  movedToPosition: function movedToPosition(_ref2) {
+    var itemLabel = _ref2.itemLabel,
+      zoneLabel = _ref2.zoneLabel,
+      position = _ref2.position;
+    return "Moved item ".concat(itemLabel, " to position ").concat(position, " in the list ").concat(zoneLabel);
+  },
+  movedToZoneEnd: function movedToZoneEnd(_ref3) {
+    var itemLabel = _ref3.itemLabel,
+      zoneLabel = _ref3.zoneLabel;
+    return "Moved item ".concat(itemLabel, " to the end of the list ").concat(zoneLabel);
+  },
+  movedToZoneStart: function movedToZoneStart(_ref4) {
+    var itemLabel = _ref4.itemLabel,
+      zoneLabel = _ref4.zoneLabel;
+    return "Moved item ".concat(itemLabel, " to the beginning of the list ").concat(zoneLabel);
+  },
+  dropped: function dropped(_ref5) {
+    var itemLabel = _ref5.itemLabel;
+    return "Stopped dragging item ".concat(itemLabel);
+  },
+  zoneActiveInstruction: function zoneActiveInstruction(_ref6) {
+    var keyboardDragTrigger = _ref6.keyboardDragTrigger;
+    return "Tab to one the items and press ".concat(KEYBOARD_DRAG_TRIGGER_PHRASES[keyboardDragTrigger], " to start dragging it");
+  },
+  zoneDragDisabledInstruction: "This is a disabled drag and drop list"
+};
+var FUNCTION_ARIA_STRING_KEYS = ["dragStarted", "movedToPosition", "movedToZoneEnd", "movedToZoneStart", "dropped"];
+// zoneActiveInstruction names the key that starts a drag, so a translation may need to vary it with the trigger.
+var STRING_OR_FUNCTION_ARIA_STRING_KEYS = ["zoneActiveInstruction"];
+// zoneDragDisabledInstruction has no drag to start and thus no key to name, so it stays string-only.
+var STRING_ONLY_ARIA_STRING_KEYS = ["zoneDragDisabledInstruction"];
+var ariaStrings = _objectSpread2({}, DEFAULT_ARIA_STRINGS);
+var instructionCtx = {
+  keyboardDragTrigger: DEFAULT_KEYBOARD_DRAG_TRIGGER
+};
 var ALERT_DIV_ID = "dnd-action-aria-alert";
 var alertsDiv;
 function initAriaOnBrowser() {
@@ -2232,11 +2292,11 @@ function initAriaOnBrowser() {
   document.body.prepend(alertsDiv);
 
   // setting the instructions
-  Object.entries(ID_TO_INSTRUCTION).forEach(function (_ref) {
-    var _ref2 = _slicedToArray(_ref, 2),
-      id = _ref2[0],
-      txt = _ref2[1];
-    return document.body.prepend(instructionToHiddenDiv(id, txt));
+  Object.entries(INSTRUCTION_ID_TO_STRING_KEY).forEach(function (_ref7) {
+    var _ref8 = _slicedToArray(_ref7, 2),
+      id = _ref8[0],
+      key = _ref8[1];
+    return document.body.prepend(instructionToHiddenDiv(id, formatWithFallback(key, instructionCtx)));
   });
 }
 
@@ -2259,7 +2319,7 @@ function initAria() {
  */
 function destroyAria() {
   if (isOnServer || !alertsDiv) return;
-  Object.keys(ID_TO_INSTRUCTION).forEach(function (id) {
+  Object.keys(INSTRUCTION_ID_TO_STRING_KEY).forEach(function (id) {
     var _document$getElementB;
     return (_document$getElementB = document.getElementById(id)) === null || _document$getElementB === void 0 ? void 0 : _document$getElementB.remove();
   });
@@ -2269,12 +2329,18 @@ function destroyAria() {
 function instructionToHiddenDiv(id, txt) {
   var div = document.createElement("div");
   div.id = id;
-  div.innerHTML = "<p>".concat(txt, "</p>");
+  renderInstruction(div, txt);
   div.style.display = "none";
   div.style.position = "fixed";
   div.style.zIndex = "-5";
   return div;
 }
+function renderInstruction(div, txt) {
+  div.replaceChildren();
+  var paragraph = document.createElement("p");
+  paragraph.textContent = txt;
+  div.appendChild(paragraph);
+}
 
 /**
  * Will make the screen reader alert the provided text to the user
@@ -2293,6 +2359,133 @@ function alertToScreenReader(txt) {
   alertsDiv.style.display = "inline";
 }
 
+/**
+ * Overrides the strings the library announces to screen readers. Each call starts with the built-in
+ * English defaults and applies the supplied overrides, so omitted keys return to English when the locale
+ * changes. Existing instruction elements update immediately. This setting is global to all dndzones.
+ * Pass null to restore the built-in English strings.
+ * @param {Object | null} overrides - any subset of: dragStarted, movedToPosition, movedToZoneEnd,
+ * movedToZoneStart, dropped (functions taking a context object and returning a string);
+ * zoneActiveInstruction (a string, or a function taking {keyboardDragTrigger} and returning a string -
+ * useful because a hard-coded translation can't name the right key if the app varies the trigger);
+ * zoneDragDisabledInstruction (a string only - a disabled zone has no drag to start, so there is no key
+ * for a formatter to name)
+ * @throws {Error} if overrides is not an object or null, contains an unknown key, or contains a value of
+ * the wrong type. Validation completes before the active strings change.
+ */
+function setAriaStrings(overrides) {
+  if (overrides === null || overrides === undefined) {
+    ariaStrings = _objectSpread2({}, DEFAULT_ARIA_STRINGS);
+  } else {
+    if (_typeof(overrides) !== "object" || Array.isArray(overrides)) {
+      throw new Error("setAriaStrings expects an object or null but instead got a ".concat(_typeof(overrides), ", ").concat(toString(overrides)));
+    }
+    Object.keys(overrides).forEach(function (key) {
+      if (!Object.prototype.hasOwnProperty.call(DEFAULT_ARIA_STRINGS, key)) {
+        throw new Error("Can't set non existing aria string ".concat(key, "! Supported strings: ").concat(Object.keys(DEFAULT_ARIA_STRINGS)));
+      }
+      var value = overrides[key];
+      if (FUNCTION_ARIA_STRING_KEYS.includes(key) && typeof value !== "function") {
+        throw new Error("".concat(key, " should be a function but instead it is a ").concat(_typeof(value), ", ").concat(toString(value)));
+      }
+      if (STRING_OR_FUNCTION_ARIA_STRING_KEYS.includes(key) && typeof value !== "string" && typeof value !== "function") {
+        throw new Error("".concat(key, " should be a string or a function but instead it is a ").concat(_typeof(value), ", ").concat(toString(value)));
+      }
+      if (STRING_ONLY_ARIA_STRING_KEYS.includes(key) && typeof value !== "string") {
+        throw new Error("".concat(key, " should be a string but instead it is a ").concat(_typeof(value), ", ").concat(toString(value)));
+      }
+    });
+    ariaStrings = _objectSpread2(_objectSpread2({}, DEFAULT_ARIA_STRINGS), overrides);
+  }
+  refreshInstructions();
+}
+function formatAriaString(strings, key, ctx) {
+  var ariaString = strings[key];
+  return typeof ariaString === "function" ? ariaString(ctx) : ariaString;
+}
+function formatWithFallback(key, ctx) {
+  try {
+    return formatAriaString(ariaStrings, key, ctx);
+  } catch (err) {
+    printDebug(function () {
+      return ["aria string formatter for \"".concat(key, "\" threw, falling back to the default"), err];
+    });
+    try {
+      return formatAriaString(DEFAULT_ARIA_STRINGS, key, ctx);
+    } catch (defaultErr) {
+      printDebug(function () {
+        return ["default aria string formatter for \"".concat(key, "\" also threw"), defaultErr];
+      });
+      return "";
+    }
+  }
+}
+function refreshInstructions() {
+  if (isOnServer) return;
+  Object.entries(INSTRUCTION_ID_TO_STRING_KEY).forEach(function (_ref9) {
+    var _ref10 = _slicedToArray(_ref9, 2),
+      id = _ref10[0],
+      key = _ref10[1];
+    var div = document.getElementById(id);
+    if (div) renderInstruction(div, formatWithFallback(key, instructionCtx));
+  });
+}
+
+/**
+ * Sets the context the static instruction formatters receive, and re-renders them. Internal - the
+ * public entry point is setKeyboardDragTrigger.
+ * @param {{keyboardDragTrigger: "space"|"enter"|"space_or_enter"}} ctx
+ */
+function setInstructionContext(ctx) {
+  instructionCtx = _objectSpread2({}, ctx);
+  refreshInstructions();
+}
+
+/**
+ * Formats and announces one configured ARIA message. If a consumer formatter throws, the built-in
+ * English formatter is used and the error is reported through printDebug. Formatter errors must not
+ * escape because this function runs during the drag lifecycle.
+ * @param {string} key - one of the keys accepted by setAriaStrings
+ * @param {Object} [ctx] - the interpolation context for that key
+ */
+function announceToScreenReader(key, ctx) {
+  alertToScreenReader(formatWithFallback(key, ctx));
+}
+
+var activeTrigger = DEFAULT_KEYBOARD_DRAG_TRIGGER;
+
+/**
+ * Chooses which key(s) start and stop a keyboard drag on a focused item. Keys outside the trigger are
+ * left completely untouched by the library (no preventDefault, no stopPropagation), so the app can use
+ * them - ex: "space" keeps Enter free to activate the focused item.
+ * This setting is global to the document and applies to every dndzone. It can be called at any time.
+ * Pass null or undefined (or call with no argument) to restore the default, "space_or_enter".
+ * @param {"space"|"enter"|"space_or_enter"|null|undefined} [trigger]
+ * @throws {Error} if given anything other than the documented values, null, or undefined
+ */
+function setKeyboardDragTrigger(trigger) {
+  if (trigger === null || trigger === undefined) {
+    activeTrigger = DEFAULT_KEYBOARD_DRAG_TRIGGER;
+  } else if (typeof trigger !== "string" || !Object.prototype.hasOwnProperty.call(KEYBOARD_DRAG_TRIGGER_KEYS, trigger)) {
+    throw new Error("setKeyboardDragTrigger expects one of ".concat(Object.keys(KEYBOARD_DRAG_TRIGGER_KEYS).map(function (key) {
+      return "\"".concat(key, "\"");
+    }).join(", "), " or null but instead got a ").concat(_typeof(trigger), ", ").concat(toString(trigger)));
+  } else {
+    activeTrigger = trigger;
+  }
+  setInstructionContext({
+    keyboardDragTrigger: activeTrigger
+  });
+}
+
+/**
+ * @param {string} key - a KeyboardEvent.key value
+ * @return {boolean} whether this key starts/stops a drag under the active trigger
+ */
+function isKeyboardDragTriggerKey(key) {
+  return KEYBOARD_DRAG_TRIGGER_KEYS[activeTrigger].includes(key);
+}
+
 var DEFAULT_DROP_ZONE_TYPE = "--any--";
 var DEFAULT_DROP_TARGET_STYLE = {
   outline: "rgba(255, 255, 102, 0.7) solid 2px"
@@ -2422,12 +2615,22 @@ function handleZoneFocus(e) {
   if (newlyFocusedDz.getBoundingClientRect().top < focusedDz.getBoundingClientRect().top || newlyFocusedDz.getBoundingClientRect().left < focusedDz.getBoundingClientRect().left) {
     targetItems.push(itemToMove);
     if (!autoAriaDisabled) {
-      alertToScreenReader("Moved item ".concat(focusedItemLabel, " to the end of the list ").concat(focusedDzLabel));
+      announceToScreenReader("movedToZoneEnd", {
+        itemLabel: focusedItemLabel,
+        zoneLabel: focusedDzLabel,
+        position: targetItems.length,
+        count: targetItems.length
+      });
     }
   } else {
     targetItems.unshift(itemToMove);
     if (!autoAriaDisabled) {
-      alertToScreenReader("Moved item ".concat(focusedItemLabel, " to the beginning of the list ").concat(focusedDzLabel));
+      announceToScreenReader("movedToZoneStart", {
+        itemLabel: focusedItemLabel,
+        zoneLabel: focusedDzLabel,
+        position: 1,
+        count: targetItems.length
+      });
     }
   }
   var dzFrom = focusedDz;
@@ -2464,7 +2667,17 @@ function handleDrop() {
   var droppedItemType = draggedItemType;
   if (!droppedConfig) return;
   if (!droppedConfig.autoAriaDisabled) {
-    alertToScreenReader("Stopped dragging item ".concat(focusedItemLabel));
+    // Include the destination and final position so localized messages can describe the completed drop.
+    var droppedItems = droppedConfig.items;
+    var droppedIdx = droppedItems.findIndex(function (item) {
+      return item[ITEM_ID_KEY] === droppedItemId;
+    });
+    announceToScreenReader("dropped", {
+      itemLabel: focusedItemLabel,
+      zoneLabel: focusedDzLabel,
+      position: (droppedIdx < 0 ? 0 : droppedIdx) + 1,
+      count: droppedItems.length
+    });
   }
   if (allDragTargets.has(document.activeElement)) {
     document.activeElement.blur();
@@ -2521,6 +2734,10 @@ function dndzone$1(node, options) {
       case "Enter":
       case " ":
         {
+          // keys outside the configured trigger belong to the consumer - don't claim them in any way
+          if (!isKeyboardDragTriggerKey(e.key)) {
+            return;
+          }
           // we don't want to affect nested input elements or clickable elements
           if ((e.target.disabled !== undefined || e.target.href || e.target.isContentEditable) && !allDragTargets.has(e.target)) {
             return;
@@ -2551,7 +2768,12 @@ function dndzone$1(node, options) {
           });
           if (idx < children.length - 1) {
             if (!config.autoAriaDisabled) {
-              alertToScreenReader("Moved item ".concat(focusedItemLabel, " to position ").concat(idx + 2, " in the list ").concat(focusedDzLabel));
+              announceToScreenReader("movedToPosition", {
+                itemLabel: focusedItemLabel,
+                zoneLabel: focusedDzLabel,
+                position: idx + 2,
+                count: items.length
+              });
             }
             swap(items, idx, idx + 1);
             dispatchFinalizeEvent(node, items, {
@@ -2577,7 +2799,12 @@ function dndzone$1(node, options) {
           });
           if (_idx > 0) {
             if (!config.autoAriaDisabled) {
-              alertToScreenReader("Moved item ".concat(focusedItemLabel, " to position ").concat(_idx, " in the list ").concat(focusedDzLabel));
+              announceToScreenReader("movedToPosition", {
+                itemLabel: focusedItemLabel,
+                zoneLabel: focusedDzLabel,
+                position: _idx,
+                count: _items.length
+              });
             }
             swap(_items, _idx, _idx - 1);
             dispatchFinalizeEvent(node, _items, {
@@ -2608,11 +2835,18 @@ function dndzone$1(node, options) {
       return dzToConfig.get(dz).dropTargetClasses;
     });
     if (!config.autoAriaDisabled) {
-      var msg = "Started dragging item ".concat(focusedItemLabel, ". Use the arrow keys to move it within its list ").concat(focusedDzLabel);
-      if (dropTargets.length > 1) {
-        msg += ", or tab to another list in order to move the item into it";
-      }
-      alertToScreenReader(msg);
+      // Include the starting position so localized messages can describe where the item was picked up.
+      var startItems = dzToConfig.get(node).items;
+      var startIdx = startItems.findIndex(function (item) {
+        return item[ITEM_ID_KEY] === focusedItemId;
+      });
+      announceToScreenReader("dragStarted", {
+        itemLabel: focusedItemLabel,
+        zoneLabel: focusedDzLabel,
+        position: (startIdx < 0 ? 0 : startIdx) + 1,
+        count: startItems.length,
+        canMoveBetweenZones: dropTargets.length > 1
+      });
     }
     dispatchConsiderEvent(node, dzToConfig.get(node).items, {
       trigger: TRIGGERS.DRAG_STARTED,
@@ -2989,7 +3223,7 @@ function dragHandle(handle) {
     window.addEventListener("touchend", resetStartDrag);
   }
   function handleKeyDown(e) {
-    if (e.key === "Enter" || e.key === " ") isItemsDragDisabled.set(false);
+    if (isKeyboardDragTriggerKey(e.key)) isItemsDragDisabled.set(false);
   }
   function resetStartDrag() {
     isItemsDragDisabled.set(true);
@@ -3026,4 +3260,4 @@ function dragHandle(handle) {
   };
 }
 
-export { DRAGGED_ELEMENT_ID, FEATURE_FLAG_NAMES, SHADOW_ITEM_MARKER_PROPERTY_NAME, SHADOW_PLACEHOLDER_ITEM_ID, SOURCES, TRIGGERS, alertToScreenReader, dndzone, dragHandle, dragHandleZone, overrideItemIdKeyNameBeforeInitialisingDndZones, setDebugMode, setFeatureFlag };
+export { DRAGGED_ELEMENT_ID, FEATURE_FLAG_NAMES, SHADOW_ITEM_MARKER_PROPERTY_NAME, SHADOW_PLACEHOLDER_ITEM_ID, SOURCES, TRIGGERS, alertToScreenReader, dndzone, dragHandle, dragHandleZone, overrideItemIdKeyNameBeforeInitialisingDndZones, setAriaStrings, setDebugMode, setFeatureFlag, setKeyboardDragTrigger };

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "svelte-dnd-action",
     "description": "*An awesome drag and drop library for Svelte 3 and 4 (not using the browser's built-in dnd, thanks god): Rich animations, nested containers, touch support and more *",
-    "version": "0.9.76",
+    "version": "0.9.78",
     "repository": {
         "type": "git",
         "url": "git+https://github.com/isaacHagoel/svelte-dnd-action.git"

package/src/constants.js

@@ -18,6 +18,24 @@ export const SOURCES = {
     KEYBOARD: "keyboard"
 };
 
+// Maps each valid global keyboardDragTrigger value (see setKeyboardDragTrigger) to the
+// KeyboardEvent.key values it covers. Keys that are not part of the active trigger are left
+// completely untouched by the library.
+export const KEYBOARD_DRAG_TRIGGER_KEYS = {
+    space: [" "],
+    enter: ["Enter"],
+    space_or_enter: [" ", "Enter"]
+};
+export const DEFAULT_KEYBOARD_DRAG_TRIGGER = "space_or_enter";
+
+// Human-readable phrase for each trigger, used by the default screen-reader instruction (see
+// src/helpers/aria.js). Must have exactly the same keys as KEYBOARD_DRAG_TRIGGER_KEYS above.
+export const KEYBOARD_DRAG_TRIGGER_PHRASES = {
+    space: "space-bar",
+    enter: "enter",
+    space_or_enter: "space-bar or enter"
+};
+
 export const SHADOW_ITEM_MARKER_PROPERTY_NAME = "isDndShadowItem";
 export const SHADOW_ELEMENT_ATTRIBUTE_NAME = "data-is-dnd-shadow-item-internal";
 export const SHADOW_ELEMENT_HINT_ATTRIBUTE_NAME = "data-is-dnd-shadow-item-hint";

package/src/helpers/aria.js

@@ -1,14 +1,37 @@
-import {isOnServer} from "../constants";
+import {DEFAULT_KEYBOARD_DRAG_TRIGGER, KEYBOARD_DRAG_TRIGGER_PHRASES, isOnServer, printDebug} from "../constants";
+import {toString} from "./util";
 
 const INSTRUCTION_IDs = {
     DND_ZONE_ACTIVE: "dnd-zone-active",
     DND_ZONE_DRAG_DISABLED: "dnd-zone-drag-disabled"
 };
-const ID_TO_INSTRUCTION = {
-    [INSTRUCTION_IDs.DND_ZONE_ACTIVE]: "Tab to one the items and press space-bar or enter to start dragging it",
-    [INSTRUCTION_IDs.DND_ZONE_DRAG_DISABLED]: "This is a disabled drag and drop list"
+const INSTRUCTION_ID_TO_STRING_KEY = {
+    [INSTRUCTION_IDs.DND_ZONE_ACTIVE]: "zoneActiveInstruction",
+    [INSTRUCTION_IDs.DND_ZONE_DRAG_DISABLED]: "zoneDragDisabledInstruction"
 };
 
+const DEFAULT_ARIA_STRINGS = {
+    dragStarted: ({itemLabel, zoneLabel, canMoveBetweenZones}) =>
+        `Started dragging item ${itemLabel}. Use the arrow keys to move it within its list ${zoneLabel}` +
+        (canMoveBetweenZones ? ", or tab to another list in order to move the item into it" : ""),
+    movedToPosition: ({itemLabel, zoneLabel, position}) => `Moved item ${itemLabel} to position ${position} in the list ${zoneLabel}`,
+    movedToZoneEnd: ({itemLabel, zoneLabel}) => `Moved item ${itemLabel} to the end of the list ${zoneLabel}`,
+    movedToZoneStart: ({itemLabel, zoneLabel}) => `Moved item ${itemLabel} to the beginning of the list ${zoneLabel}`,
+    dropped: ({itemLabel}) => `Stopped dragging item ${itemLabel}`,
+    zoneActiveInstruction: ({keyboardDragTrigger}) =>
+        `Tab to one the items and press ${KEYBOARD_DRAG_TRIGGER_PHRASES[keyboardDragTrigger]} to start dragging it`,
+    zoneDragDisabledInstruction: "This is a disabled drag and drop list"
+};
+
+const FUNCTION_ARIA_STRING_KEYS = ["dragStarted", "movedToPosition", "movedToZoneEnd", "movedToZoneStart", "dropped"];
+// zoneActiveInstruction names the key that starts a drag, so a translation may need to vary it with the trigger.
+const STRING_OR_FUNCTION_ARIA_STRING_KEYS = ["zoneActiveInstruction"];
+// zoneDragDisabledInstruction has no drag to start and thus no key to name, so it stays string-only.
+const STRING_ONLY_ARIA_STRING_KEYS = ["zoneDragDisabledInstruction"];
+
+let ariaStrings = {...DEFAULT_ARIA_STRINGS};
+let instructionCtx = {keyboardDragTrigger: DEFAULT_KEYBOARD_DRAG_TRIGGER};
+
 const ALERT_DIV_ID = "dnd-action-aria-alert";
 let alertsDiv;
 
@@ -35,7 +58,9 @@ function initAriaOnBrowser() {
     document.body.prepend(alertsDiv);
 
     // setting the instructions
-    Object.entries(ID_TO_INSTRUCTION).forEach(([id, txt]) => document.body.prepend(instructionToHiddenDiv(id, txt)));
+    Object.entries(INSTRUCTION_ID_TO_STRING_KEY).forEach(([id, key]) =>
+        document.body.prepend(instructionToHiddenDiv(id, formatWithFallback(key, instructionCtx)))
+    );
 }
 
 /**
@@ -57,7 +82,7 @@ export function initAria() {
  */
 export function destroyAria() {
     if (isOnServer || !alertsDiv) return;
-    Object.keys(ID_TO_INSTRUCTION).forEach(id => document.getElementById(id)?.remove());
+    Object.keys(INSTRUCTION_ID_TO_STRING_KEY).forEach(id => document.getElementById(id)?.remove());
     alertsDiv.remove();
     alertsDiv = undefined;
 }
@@ -65,13 +90,20 @@ export function destroyAria() {
 function instructionToHiddenDiv(id, txt) {
     const div = document.createElement("div");
     div.id = id;
-    div.innerHTML = `<p>${txt}</p>`;
+    renderInstruction(div, txt);
     div.style.display = "none";
     div.style.position = "fixed";
     div.style.zIndex = "-5";
     return div;
 }
 
+function renderInstruction(div, txt) {
+    div.replaceChildren();
+    const paragraph = document.createElement("p");
+    paragraph.textContent = txt;
+    div.appendChild(paragraph);
+}
+
 /**
  * Will make the screen reader alert the provided text to the user
  * @param {string} txt
@@ -88,3 +120,92 @@ export function alertToScreenReader(txt) {
     alertsDiv.style.display = "none";
     alertsDiv.style.display = "inline";
 }
+
+/**
+ * Overrides the strings the library announces to screen readers. Each call starts with the built-in
+ * English defaults and applies the supplied overrides, so omitted keys return to English when the locale
+ * changes. Existing instruction elements update immediately. This setting is global to all dndzones.
+ * Pass null to restore the built-in English strings.
+ * @param {Object | null} overrides - any subset of: dragStarted, movedToPosition, movedToZoneEnd,
+ * movedToZoneStart, dropped (functions taking a context object and returning a string);
+ * zoneActiveInstruction (a string, or a function taking {keyboardDragTrigger} and returning a string -
+ * useful because a hard-coded translation can't name the right key if the app varies the trigger);
+ * zoneDragDisabledInstruction (a string only - a disabled zone has no drag to start, so there is no key
+ * for a formatter to name)
+ * @throws {Error} if overrides is not an object or null, contains an unknown key, or contains a value of
+ * the wrong type. Validation completes before the active strings change.
+ */
+export function setAriaStrings(overrides) {
+    if (overrides === null || overrides === undefined) {
+        ariaStrings = {...DEFAULT_ARIA_STRINGS};
+    } else {
+        if (typeof overrides !== "object" || Array.isArray(overrides)) {
+            throw new Error(`setAriaStrings expects an object or null but instead got a ${typeof overrides}, ${toString(overrides)}`);
+        }
+        Object.keys(overrides).forEach(key => {
+            if (!Object.prototype.hasOwnProperty.call(DEFAULT_ARIA_STRINGS, key)) {
+                throw new Error(`Can't set non existing aria string ${key}! Supported strings: ${Object.keys(DEFAULT_ARIA_STRINGS)}`);
+            }
+            const value = overrides[key];
+            if (FUNCTION_ARIA_STRING_KEYS.includes(key) && typeof value !== "function") {
+                throw new Error(`${key} should be a function but instead it is a ${typeof value}, ${toString(value)}`);
+            }
+            if (STRING_OR_FUNCTION_ARIA_STRING_KEYS.includes(key) && typeof value !== "string" && typeof value !== "function") {
+                throw new Error(`${key} should be a string or a function but instead it is a ${typeof value}, ${toString(value)}`);
+            }
+            if (STRING_ONLY_ARIA_STRING_KEYS.includes(key) && typeof value !== "string") {
+                throw new Error(`${key} should be a string but instead it is a ${typeof value}, ${toString(value)}`);
+            }
+        });
+        ariaStrings = {...DEFAULT_ARIA_STRINGS, ...overrides};
+    }
+    refreshInstructions();
+}
+
+function formatAriaString(strings, key, ctx) {
+    const ariaString = strings[key];
+    return typeof ariaString === "function" ? ariaString(ctx) : ariaString;
+}
+
+function formatWithFallback(key, ctx) {
+    try {
+        return formatAriaString(ariaStrings, key, ctx);
+    } catch (err) {
+        printDebug(() => [`aria string formatter for "${key}" threw, falling back to the default`, err]);
+        try {
+            return formatAriaString(DEFAULT_ARIA_STRINGS, key, ctx);
+        } catch (defaultErr) {
+            printDebug(() => [`default aria string formatter for "${key}" also threw`, defaultErr]);
+            return "";
+        }
+    }
+}
+
+function refreshInstructions() {
+    if (isOnServer) return;
+    Object.entries(INSTRUCTION_ID_TO_STRING_KEY).forEach(([id, key]) => {
+        const div = document.getElementById(id);
+        if (div) renderInstruction(div, formatWithFallback(key, instructionCtx));
+    });
+}
+
+/**
+ * Sets the context the static instruction formatters receive, and re-renders them. Internal - the
+ * public entry point is setKeyboardDragTrigger.
+ * @param {{keyboardDragTrigger: "space"|"enter"|"space_or_enter"}} ctx
+ */
+export function setInstructionContext(ctx) {
+    instructionCtx = {...ctx};
+    refreshInstructions();
+}
+
+/**
+ * Formats and announces one configured ARIA message. If a consumer formatter throws, the built-in
+ * English formatter is used and the error is reported through printDebug. Formatter errors must not
+ * escape because this function runs during the drag lifecycle.
+ * @param {string} key - one of the keys accepted by setAriaStrings
+ * @param {Object} [ctx] - the interpolation context for that key
+ */
+export function announceToScreenReader(key, ctx) {
+    alertToScreenReader(formatWithFallback(key, ctx));
+}

package/src/index.js

@@ -1,6 +1,7 @@
 export {dndzone} from "./action.js";
 export {dragHandleZone, dragHandle} from "./wrappers/withDragHandles";
-export {alertToScreenReader} from "./helpers/aria";
+export {alertToScreenReader, setAriaStrings} from "./helpers/aria";
+export {setKeyboardDragTrigger} from "./keyboardDragTrigger";
 export {
     TRIGGERS,
     SOURCES,

package/src/keyboardAction.js

@@ -1,7 +1,8 @@
 import {decrementActiveDropZoneCount, incrementActiveDropZoneCount, ITEM_ID_KEY, SOURCES, TRIGGERS} from "./constants";
+import {isKeyboardDragTriggerKey} from "./keyboardDragTrigger";
 import {styleActiveDropZones, styleInactiveDropZones} from "./helpers/styler";
 import {dispatchConsiderEvent, dispatchFinalizeEvent} from "./helpers/dispatcher";
-import {initAria, alertToScreenReader, destroyAria} from "./helpers/aria";
+import {initAria, announceToScreenReader, destroyAria} from "./helpers/aria";
 import {toString} from "./helpers/util";
 import {printDebug} from "./constants";
 
@@ -124,12 +125,22 @@ function handleZoneFocus(e) {
     ) {
         targetItems.push(itemToMove);
         if (!autoAriaDisabled) {
-            alertToScreenReader(`Moved item ${focusedItemLabel} to the end of the list ${focusedDzLabel}`);
+            announceToScreenReader("movedToZoneEnd", {
+                itemLabel: focusedItemLabel,
+                zoneLabel: focusedDzLabel,
+                position: targetItems.length,
+                count: targetItems.length
+            });
         }
     } else {
         targetItems.unshift(itemToMove);
         if (!autoAriaDisabled) {
-            alertToScreenReader(`Moved item ${focusedItemLabel} to the beginning of the list ${focusedDzLabel}`);
+            announceToScreenReader("movedToZoneStart", {
+                itemLabel: focusedItemLabel,
+                zoneLabel: focusedDzLabel,
+                position: 1,
+                count: targetItems.length
+            });
         }
     }
     const dzFrom = focusedDz;
@@ -155,7 +166,15 @@ function handleDrop(dispatchConsider = true) {
     if (!droppedConfig) return;
 
     if (!droppedConfig.autoAriaDisabled) {
-        alertToScreenReader(`Stopped dragging item ${focusedItemLabel}`);
+        // Include the destination and final position so localized messages can describe the completed drop.
+        const droppedItems = droppedConfig.items;
+        const droppedIdx = droppedItems.findIndex(item => item[ITEM_ID_KEY] === droppedItemId);
+        announceToScreenReader("dropped", {
+            itemLabel: focusedItemLabel,
+            zoneLabel: focusedDzLabel,
+            position: (droppedIdx < 0 ? 0 : droppedIdx) + 1,
+            count: droppedItems.length
+        });
     }
     if (allDragTargets.has(document.activeElement)) {
         document.activeElement.blur();
@@ -212,6 +231,10 @@ export function dndzone(node, options) {
         switch (e.key) {
             case "Enter":
             case " ": {
+                // keys outside the configured trigger belong to the consumer - don't claim them in any way
+                if (!isKeyboardDragTriggerKey(e.key)) {
+                    return;
+                }
                 // we don't want to affect nested input elements or clickable elements
                 if ((e.target.disabled !== undefined || e.target.href || e.target.isContentEditable) && !allDragTargets.has(e.target)) {
                     return;
@@ -238,7 +261,12 @@ export function dndzone(node, options) {
                 printDebug(() => ["arrow down", idx]);
                 if (idx < children.length - 1) {
                     if (!config.autoAriaDisabled) {
-                        alertToScreenReader(`Moved item ${focusedItemLabel} to position ${idx + 2} in the list ${focusedDzLabel}`);
+                        announceToScreenReader("movedToPosition", {
+                            itemLabel: focusedItemLabel,
+                            zoneLabel: focusedDzLabel,
+                            position: idx + 2,
+                            count: items.length
+                        });
                     }
                     swap(items, idx, idx + 1);
                     dispatchFinalizeEvent(node, items, {trigger: TRIGGERS.DROPPED_INTO_ZONE, id: focusedItemId, source: SOURCES.KEYBOARD});
@@ -256,7 +284,12 @@ export function dndzone(node, options) {
                 printDebug(() => ["arrow up", idx]);
                 if (idx > 0) {
                     if (!config.autoAriaDisabled) {
-                        alertToScreenReader(`Moved item ${focusedItemLabel} to position ${idx} in the list ${focusedDzLabel}`);
+                        announceToScreenReader("movedToPosition", {
+                            itemLabel: focusedItemLabel,
+                            zoneLabel: focusedDzLabel,
+                            position: idx,
+                            count: items.length
+                        });
                     }
                     swap(items, idx, idx - 1);
                     dispatchFinalizeEvent(node, items, {trigger: TRIGGERS.DROPPED_INTO_ZONE, id: focusedItemId, source: SOURCES.KEYBOARD});
@@ -279,11 +312,16 @@ export function dndzone(node, options) {
             dz => dzToConfig.get(dz).dropTargetClasses
         );
         if (!config.autoAriaDisabled) {
-            let msg = `Started dragging item ${focusedItemLabel}. Use the arrow keys to move it within its list ${focusedDzLabel}`;
-            if (dropTargets.length > 1) {
-                msg += `, or tab to another list in order to move the item into it`;
-            }
-            alertToScreenReader(msg);
+            // Include the starting position so localized messages can describe where the item was picked up.
+            const startItems = dzToConfig.get(node).items;
+            const startIdx = startItems.findIndex(item => item[ITEM_ID_KEY] === focusedItemId);
+            announceToScreenReader("dragStarted", {
+                itemLabel: focusedItemLabel,
+                zoneLabel: focusedDzLabel,
+                position: (startIdx < 0 ? 0 : startIdx) + 1,
+                count: startItems.length,
+                canMoveBetweenZones: dropTargets.length > 1
+            });
         }
         dispatchConsiderEvent(node, dzToConfig.get(node).items, {trigger: TRIGGERS.DRAG_STARTED, id: focusedItemId, source: SOURCES.KEYBOARD});
         triggerAllDzsUpdate();

package/src/keyboardDragTrigger.js

@@ -0,0 +1,44 @@
+import {DEFAULT_KEYBOARD_DRAG_TRIGGER, KEYBOARD_DRAG_TRIGGER_KEYS} from "./constants";
+import {toString} from "./helpers/util";
+import {setInstructionContext} from "./helpers/aria";
+
+let activeTrigger = DEFAULT_KEYBOARD_DRAG_TRIGGER;
+
+/**
+ * Chooses which key(s) start and stop a keyboard drag on a focused item. Keys outside the trigger are
+ * left completely untouched by the library (no preventDefault, no stopPropagation), so the app can use
+ * them - ex: "space" keeps Enter free to activate the focused item.
+ * This setting is global to the document and applies to every dndzone. It can be called at any time.
+ * Pass null or undefined (or call with no argument) to restore the default, "space_or_enter".
+ * @param {"space"|"enter"|"space_or_enter"|null|undefined} [trigger]
+ * @throws {Error} if given anything other than the documented values, null, or undefined
+ */
+export function setKeyboardDragTrigger(trigger) {
+    if (trigger === null || trigger === undefined) {
+        activeTrigger = DEFAULT_KEYBOARD_DRAG_TRIGGER;
+    } else if (typeof trigger !== "string" || !Object.prototype.hasOwnProperty.call(KEYBOARD_DRAG_TRIGGER_KEYS, trigger)) {
+        throw new Error(
+            `setKeyboardDragTrigger expects one of ${Object.keys(KEYBOARD_DRAG_TRIGGER_KEYS)
+                .map(key => `"${key}"`)
+                .join(", ")} or null but instead got a ${typeof trigger}, ${toString(trigger)}`
+        );
+    } else {
+        activeTrigger = trigger;
+    }
+    setInstructionContext({keyboardDragTrigger: activeTrigger});
+}
+
+/**
+ * @return {"space"|"enter"|"space_or_enter"} the active trigger
+ */
+export function getKeyboardDragTrigger() {
+    return activeTrigger;
+}
+
+/**
+ * @param {string} key - a KeyboardEvent.key value
+ * @return {boolean} whether this key starts/stops a drag under the active trigger
+ */
+export function isKeyboardDragTriggerKey(key) {
+    return KEYBOARD_DRAG_TRIGGER_KEYS[activeTrigger].includes(key);
+}

package/src/wrappers/withDragHandles.js

@@ -1,4 +1,5 @@
 import {SOURCES, TRIGGERS} from "../constants";
+import {isKeyboardDragTriggerKey} from "../keyboardDragTrigger";
 import {dndzone} from "../action";
 import {createStore} from "./simpleStore";
 
@@ -104,7 +105,7 @@ export function dragHandle(handle) {
     }
 
     function handleKeyDown(e) {
-        if (e.key === "Enter" || e.key === " ") isItemsDragDisabled.set(false);
+        if (isKeyboardDragTriggerKey(e.key)) isItemsDragDisabled.set(false);
     }
 
     function resetStartDrag() {