svelte-dnd-action 0.9.76 → 0.9.77

package/README.md

@@ -118,7 +118,7 @@ An options-object with the following attributes:
 | `dropTargetStyle` | Object<String> | 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<String> | 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,6 +167,33 @@ 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)).
 
+#### 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";
+
+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: `Tabulez jusqu'à un élément et appuyez sur espace ou entrée pour le déplacer`,
+    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.
+
+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

package/dist/index.d.ts

@@ -82,6 +82,27 @@ 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;
+    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;
+
 /**
  * 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

@@ -2207,12 +2207,45 @@
     };
   }
 
-  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: "Tab to one the items and press space-bar or enter to start dragging it",
+    zoneDragDisabledInstruction: "This is a disabled drag and drop list"
+  };
+  var FUNCTION_ARIA_STRING_KEYS = ["dragStarted", "movedToPosition", "movedToZoneEnd", "movedToZoneStart", "dropped"];
+  var STRING_ARIA_STRING_KEYS = ["zoneActiveInstruction", "zoneDragDisabledInstruction"];
+  var ariaStrings = _objectSpread2({}, DEFAULT_ARIA_STRINGS);
   var ALERT_DIV_ID = "dnd-action-aria-alert";
   var alertsDiv;
   function initAriaOnBrowser() {
@@ -2238,11 +2271,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 (_ref6) {
+      var _ref7 = _slicedToArray(_ref6, 2),
+        id = _ref7[0],
+        key = _ref7[1];
+      return document.body.prepend(instructionToHiddenDiv(id, ariaStrings[key]));
     });
   }
 
@@ -2265,7 +2298,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 +2308,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 +2338,79 @@
     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, zoneDragDisabledInstruction (strings)
+   * @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_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);
+    }
+    if (isOnServer) return;
+    Object.entries(INSTRUCTION_ID_TO_STRING_KEY).forEach(function (_ref8) {
+      var _ref9 = _slicedToArray(_ref8, 2),
+        id = _ref9[0],
+        key = _ref9[1];
+      var div = document.getElementById(id);
+      if (div) renderInstruction(div, ariaStrings[key]);
+    });
+  }
+  function formatAriaString(strings, key, ctx) {
+    var ariaString = strings[key];
+    return typeof ariaString === "function" ? ariaString(ctx) : ariaString;
+  }
+
+  /**
+   * 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) {
+    var text;
+    try {
+      text = formatAriaString(ariaStrings, key, ctx);
+    } catch (err) {
+      printDebug(function () {
+        return ["aria string formatter for \"".concat(key, "\" threw, falling back to the default"), err];
+      });
+      try {
+        text = formatAriaString(DEFAULT_ARIA_STRINGS, key, ctx);
+      } catch (defaultErr) {
+        printDebug(function () {
+          return ["default aria string formatter for \"".concat(key, "\" also threw"), defaultErr];
+        });
+        text = "";
+      }
+    }
+    alertToScreenReader(text);
+  }
+
   var DEFAULT_DROP_ZONE_TYPE = "--any--";
   var DEFAULT_DROP_TARGET_STYLE = {
     outline: "rgba(255, 255, 102, 0.7) solid 2px"
@@ -2428,12 +2540,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 +2592,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();
@@ -2557,7 +2689,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 +2720,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 +2756,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,
@@ -3043,6 +3192,7 @@
   exports.dragHandle = dragHandle;
   exports.dragHandleZone = dragHandleZone;
   exports.overrideItemIdKeyNameBeforeInitialisingDndZones = overrideItemIdKeyNameBeforeInitialisingDndZones;
+  exports.setAriaStrings = setAriaStrings;
   exports.setDebugMode = setDebugMode;
   exports.setFeatureFlag = setFeatureFlag;
 

package/dist/index.mjs

@@ -2201,12 +2201,45 @@ 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: "Tab to one the items and press space-bar or enter to start dragging it",
+  zoneDragDisabledInstruction: "This is a disabled drag and drop list"
+};
+var FUNCTION_ARIA_STRING_KEYS = ["dragStarted", "movedToPosition", "movedToZoneEnd", "movedToZoneStart", "dropped"];
+var STRING_ARIA_STRING_KEYS = ["zoneActiveInstruction", "zoneDragDisabledInstruction"];
+var ariaStrings = _objectSpread2({}, DEFAULT_ARIA_STRINGS);
 var ALERT_DIV_ID = "dnd-action-aria-alert";
 var alertsDiv;
 function initAriaOnBrowser() {
@@ -2232,11 +2265,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 (_ref6) {
+    var _ref7 = _slicedToArray(_ref6, 2),
+      id = _ref7[0],
+      key = _ref7[1];
+    return document.body.prepend(instructionToHiddenDiv(id, ariaStrings[key]));
   });
 }
 
@@ -2259,7 +2292,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 +2302,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 +2332,79 @@ 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, zoneDragDisabledInstruction (strings)
+ * @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_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);
+  }
+  if (isOnServer) return;
+  Object.entries(INSTRUCTION_ID_TO_STRING_KEY).forEach(function (_ref8) {
+    var _ref9 = _slicedToArray(_ref8, 2),
+      id = _ref9[0],
+      key = _ref9[1];
+    var div = document.getElementById(id);
+    if (div) renderInstruction(div, ariaStrings[key]);
+  });
+}
+function formatAriaString(strings, key, ctx) {
+  var ariaString = strings[key];
+  return typeof ariaString === "function" ? ariaString(ctx) : ariaString;
+}
+
+/**
+ * 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) {
+  var text;
+  try {
+    text = formatAriaString(ariaStrings, key, ctx);
+  } catch (err) {
+    printDebug(function () {
+      return ["aria string formatter for \"".concat(key, "\" threw, falling back to the default"), err];
+    });
+    try {
+      text = formatAriaString(DEFAULT_ARIA_STRINGS, key, ctx);
+    } catch (defaultErr) {
+      printDebug(function () {
+        return ["default aria string formatter for \"".concat(key, "\" also threw"), defaultErr];
+      });
+      text = "";
+    }
+  }
+  alertToScreenReader(text);
+}
+
 var DEFAULT_DROP_ZONE_TYPE = "--any--";
 var DEFAULT_DROP_TARGET_STYLE = {
   outline: "rgba(255, 255, 102, 0.7) solid 2px"
@@ -2422,12 +2534,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 +2586,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();
@@ -2551,7 +2683,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 +2714,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 +2750,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,
@@ -3026,4 +3175,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 };

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.77",
     "repository": {
         "type": "git",
         "url": "git+https://github.com/isaacHagoel/svelte-dnd-action.git"

package/src/helpers/aria.js

@@ -1,14 +1,32 @@
-import {isOnServer} from "../constants";
+import {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: "Tab to one the items and press space-bar or enter to start dragging it",
+    zoneDragDisabledInstruction: "This is a disabled drag and drop list"
+};
+
+const FUNCTION_ARIA_STRING_KEYS = ["dragStarted", "movedToPosition", "movedToZoneEnd", "movedToZoneStart", "dropped"];
+const STRING_ARIA_STRING_KEYS = ["zoneActiveInstruction", "zoneDragDisabledInstruction"];
+
+let ariaStrings = {...DEFAULT_ARIA_STRINGS};
+
 const ALERT_DIV_ID = "dnd-action-aria-alert";
 let alertsDiv;
 
@@ -35,7 +53,7 @@ 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, ariaStrings[key])));
 }
 
 /**
@@ -57,7 +75,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 +83,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 +113,70 @@ 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, zoneDragDisabledInstruction (strings)
+ * @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_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};
+    }
+    if (isOnServer) return;
+    Object.entries(INSTRUCTION_ID_TO_STRING_KEY).forEach(([id, key]) => {
+        const div = document.getElementById(id);
+        if (div) renderInstruction(div, ariaStrings[key]);
+    });
+}
+
+function formatAriaString(strings, key, ctx) {
+    const ariaString = strings[key];
+    return typeof ariaString === "function" ? ariaString(ctx) : ariaString;
+}
+
+/**
+ * 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) {
+    let text;
+    try {
+        text = formatAriaString(ariaStrings, key, ctx);
+    } catch (err) {
+        printDebug(() => [`aria string formatter for "${key}" threw, falling back to the default`, err]);
+        try {
+            text = formatAriaString(DEFAULT_ARIA_STRINGS, key, ctx);
+        } catch (defaultErr) {
+            printDebug(() => [`default aria string formatter for "${key}" also threw`, defaultErr]);
+            text = "";
+        }
+    }
+    alertToScreenReader(text);
+}

package/src/index.js

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

package/src/keyboardAction.js

@@ -1,7 +1,7 @@
 import {decrementActiveDropZoneCount, incrementActiveDropZoneCount, ITEM_ID_KEY, SOURCES, TRIGGERS} from "./constants";
 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 +124,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 +165,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();
@@ -238,7 +256,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 +279,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 +307,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();